From 1f2b31f1746bf448d06b8b59491f196a1bd3a454 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Wed, 20 May 2015 15:57:49 +0300 Subject: [PATCH] Create separate Continuous Integration page --- docs/ci/index.rst | 20 +++++++++++ docs/ci/travis.rst | 72 +++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + docs/userguide/cmd_ci.rst | 12 ++----- 4 files changed, 95 insertions(+), 10 deletions(-) create mode 100644 docs/ci/index.rst create mode 100644 docs/ci/travis.rst diff --git a/docs/ci/index.rst b/docs/ci/index.rst new file mode 100644 index 00000000..d619bc24 --- /dev/null +++ b/docs/ci/index.rst @@ -0,0 +1,20 @@ +.. _ci: + +Continuous Integration +====================== + +`Continuous Integration (CI, wiki) `_ +is the practice, in software engineering, of merging all developer working +copies with a shared mainline several times a day. + +:ref:`cmd_ci` command is intended to be used in combination with the build +servers and the popular +`Continuous Integration Software `_. + +By integrating regularly, you can detect errors quickly, and locate them more +easily. + +.. toctree:: + :maxdepth: 2 + + travis diff --git a/docs/ci/travis.rst b/docs/ci/travis.rst new file mode 100644 index 00000000..4c5e9e34 --- /dev/null +++ b/docs/ci/travis.rst @@ -0,0 +1,72 @@ +.. _ci_travis: + +Travis CI +========= + +`Travis CI `_ is an open-source hosted, +distributed continuous integration service used to build and test projects +hosted at `GitHub `_. + +Travis CI is configured by adding a file named ``.travis.yml``, which is a +`YAML `_ format text file, to the root +directory of the GitHub repository. + +Travis CI automatically detects when a commit has been made and pushed to a +GitHub repository that is using Travis CI, and each time this happens, it will +try to build the project using :ref:`cmd_ci` command. This includes commits to +all branches, not just to the master branch. Travis CI will also build and run +pull requests. When that process has completed, it will notify a developer in +the way it has been configured to do so — for example, by sending an email +containing the build results (showing success or failure), or by posting a +message on an IRC channel. It can be configured to build project on a range of +different :ref:`platforms`. + +Integration +----------- + +Please put ``.travis.yml`` to the root directory of the GitHub repository. + +.. code-block:: yaml + + language: python + python: + - "2.7" + + env: + - PLATFORMIO_CI_SRC=path/to/source/file.c + - PLATFORMIO_CI_SRC=path/to/source/file.ino + - PLATFORMIO_CI_SRC=path/to/source/directory + + install: + - python -c "$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio/master/scripts/get-platformio.py)" + + script: + - platformio ci --board=TYPE_1 --board=TYPE_2 --board=TYPE_N + + +For more details as for PlatformIO build process please look into :ref:`cmd_ci` +command. + +Examples +-------- + +1. Integration for `USB_Host_Shield_2.0 `_ + project. The ``.travis.yml`` configuration file: + +.. code-block:: yaml + + language: python + python: + - "2.7" + + env: + - PLATFORMIO_CI_SRC=examples/Bluetooth/PS3SPP/PS3SPP.ino + - PLATFORMIO_CI_SRC=examples/pl2303/pl2303_gps/pl2303_gps.ino + + install: + - python -c "$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio/master/scripts/get-platformio.py)" + - wget https://github.com/xxxajk/spi4teensy3/archive/master.zip -O /tmp/spi4teensy3.zip + - unzip /tmp/spi4teensy3.zip -d /tmp + + script: + - platformio ci --lib="." --lib="/tmp/spi4teensy3-master" --board=uno --board=teensy31 --board=due diff --git a/docs/index.rst b/docs/index.rst index 830eb04b..2c580297 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -63,6 +63,7 @@ Contents frameworks/index librarymanager/index userguide/index + ci/index ide articles FAQ diff --git a/docs/userguide/cmd_ci.rst b/docs/userguide/cmd_ci.rst index bc120e4a..021ebc15 100644 --- a/docs/userguide/cmd_ci.rst +++ b/docs/userguide/cmd_ci.rst @@ -16,10 +16,6 @@ Usage Description ----------- -`Continuous integration (CI, wiki) `_ -is the practice, in software engineering, of merging all developer working -copies with a shared mainline several times a day. - :ref:`cmd_ci` command is conceived of as "hot key" for building project with arbitrary source code structure. In a nutshell, using ``SRC`` and :option:`platformio ci --lib` contents PlatformIO initialises via @@ -28,12 +24,8 @@ with the build environments (using :option:`platformio ci --board` or :option:`platformio ci --project-conf`) and processes them via :ref:`cmd_run` command. -:ref:`cmd_ci` command is intended to be used in combination with the build -servers and the popular -`Continuous Integration Software `_. - -By integrating regularly, you can detect errors quickly, and locate them more -easily. +For more details as for integration with the popular Continuous Integration +Systems please follow to :ref:`ci` page. .. note:: :ref:`cmd_ci` command accepts **multiple** ``SRC`` arguments,