From 1c63da7f33208b0e09004f412642570665808591 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Mon, 19 Oct 2015 18:25:06 +0100 Subject: [PATCH] Improve Travis CI doc --- docs/articles.rst | 2 +- docs/ci/appveyor.rst | 2 + docs/ci/circleci.rst | 2 + docs/ci/drone.rst | 2 + docs/ci/shippable.rst | 2 + docs/ci/travis.rst | 119 ++++++++++++++++++++++++++++++++++++++---- 6 files changed, 118 insertions(+), 11 deletions(-) diff --git a/docs/articles.rst b/docs/articles.rst index 5a4aa1f8..018e0b03 100644 --- a/docs/articles.rst +++ b/docs/articles.rst @@ -12,7 +12,7 @@ Here are recent articles about PlatformIO: 2015 ^^^^ -* Oct 18, 2015 - **Nico Coetzee** - `First Arduino I2C Experience with PaltformIO `_ +* Oct 18, 2015 - **Nico Coetzee** - `First Arduino I2C Experience with PlatformIO `_ * Sep 01, 2015 - **Thomas P. Weldon, Ph.D.** - `Improvised MBED FRDM-K64F Eclipse/PlatformIO Setup and Software Installation `_ * Aug 01, 2015 - **Russell Davis** - `PlatformIO on the Raspberry Pi `_ * Jul 25, 2015 - **DinoTools** - `Erste Schritte mit PlatformIO (German) `_ diff --git a/docs/ci/appveyor.rst b/docs/ci/appveyor.rst index e05ca4f2..4b87dd49 100644 --- a/docs/ci/appveyor.rst +++ b/docs/ci/appveyor.rst @@ -22,6 +22,8 @@ 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`. +.. contents:: + Integration ----------- diff --git a/docs/ci/circleci.rst b/docs/ci/circleci.rst index daf7e674..2e5ddede 100644 --- a/docs/ci/circleci.rst +++ b/docs/ci/circleci.rst @@ -21,6 +21,8 @@ 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`. +.. contents:: + Integration ----------- diff --git a/docs/ci/drone.rst b/docs/ci/drone.rst index 912b546b..155f34d4 100644 --- a/docs/ci/drone.rst +++ b/docs/ci/drone.rst @@ -20,6 +20,8 @@ the way it has been configured to do so — for example, by sending an email containing the build results (showing success or failure). It can be configured to build project on a range of different :ref:`platforms`. +.. contents:: + Integration ----------- diff --git a/docs/ci/shippable.rst b/docs/ci/shippable.rst index 9d27df52..281ad41b 100644 --- a/docs/ci/shippable.rst +++ b/docs/ci/shippable.rst @@ -24,6 +24,8 @@ 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`. +.. contents:: + Integration ----------- diff --git a/docs/ci/travis.rst b/docs/ci/travis.rst index 8eeff63d..8cd5a347 100644 --- a/docs/ci/travis.rst +++ b/docs/ci/travis.rst @@ -21,10 +21,17 @@ 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`. +.. contents:: + Integration ----------- -Please put ``.travis.yml`` to the root directory of the GitHub repository. +Please make sure to read Travis CI `Getting Started `_ +and `general build configuration `_ +guides first. + +PlatformIO is written in Python and is recommended to be run within +`Travis CI Python isolated environment `_: .. code-block:: yaml @@ -32,22 +39,106 @@ Please put ``.travis.yml`` to the root directory of the GitHub repository. python: - "2.7" + # Cache PlatformIO packages using Travis CI container-based infrastructure + sudo: false + cache: + directories: + - "~/.platformio" + env: - - PLATFORMIO_CI_SRC=path/to/source/file.c - - PLATFORMIO_CI_SRC=path/to/source/file.ino - - PLATFORMIO_CI_SRC=path/to/source/directory + - PLATFORMIO_CI_SRC=path/to/test/file.c + - PLATFORMIO_CI_SRC=examples/file.ino + - PLATFORMIO_CI_SRC=path/to/test/directory install: - - python -c "$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio/master/scripts/get-platformio.py)" + - pip install -U platformio script: - platformio ci --board=TYPE_1 --board=TYPE_2 --board=TYPE_N +Then perform steps 1, 2 and 4 from http://docs.travis-ci.com/user/getting-started/ -Then see step 1, 2, and step 4 here: http://docs.travis-ci.com/user/getting-started/ +For more details as for PlatformIO build process please look into :ref:`cmd_ci`. -For more details as for PlatformIO build process please look into :ref:`cmd_ci` -command. +Project as a library +~~~~~~~~~~~~~~~~~~~~ + +When project is written as a library (where own examples or testing code use +it), please use ``--lib="."`` option for :ref:`cmd_ci` command + +.. code-block:: yaml + + script: + - platformio ci --lib="." --board=TYPE_1 --board=TYPE_2 --board=TYPE_N + +Library dependecies +~~~~~~~~~~~~~~~~~~~ + +There 2 options to test source code with dependent libraries: + +Install dependent library using :ref:`librarymanager` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: yaml + + install: + - pip install -U platformio + + # + # Libraries from PlatformIO Library Registry: + # + # http://platformio.org/#!/lib/show/1/OneWire + platformio lib install 1 + +Manually download dependent library and include in build process via ``--lib`` option +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: yaml + + install: + - pip install -U platformio + + # download library to the temporary directory + wget https://github.com/PaulStoffregen/OneWire/archive/master.zip -O /tmp/onewire_source.zip + unzip /tmp/onewire_source.zip -d /tmp/ + + script: + - platformio ci --lib="/tmp/OneWire-master" --board=TYPE_1 --board=TYPE_2 --board=TYPE_N + +Custom Build Flags +~~~~~~~~~~~~~~~~~~ + +PlatformIO allows to specify own build flags using :envvar:`PLATFORMIO_BUILD_FLAGS` environment + +.. code-block:: yaml + + env: + - PLATFORMIO_CI_SRC=path/to/test/file.c PLATFORMIO_BUILD_FLAGS="-D SPECIFIC_MACROS_PER_TEST_ENV -I/extra/inc" + - PLATFORMIO_CI_SRC=examples/file.ino + - PLATFORMIO_CI_SRC=path/to/test/directory + + install: + - pip install -U platformio + + export PLATFORMIO_BUILD_FLAGS=-D GLOBAL_MACROS_FOR_ALL_TEST_ENV + + +For the more details, please follow to +:ref:`available build flags/options `. + + +Advanced configuration +~~~~~~~~~~~~~~~~~~~~~~ + +PlatformIO allows to configure multiple build environments for the single +source code using :ref:`projectconf`. + +Instead of ``--board`` option, please use :option:`platformio ci --project-conf` + +.. code-block:: yaml + + script: + - platformio ci --project-conf=/path/to/platoformio.ini Examples -------- @@ -61,6 +152,12 @@ Examples python: - "2.7" + # Cache PlatformIO packages using Travis CI container-based infrastructure + sudo: false + cache: + directories: + - "~/.platformio" + env: - PLATFORMIO_CI_SRC=examples/acm/acm_terminal - PLATFORMIO_CI_SRC=examples/Bluetooth/WiiIRCamera PLATFORMIO_BUILD_FLAGS="-DWIICAMERA" @@ -69,9 +166,11 @@ Examples # - ... install: - - python -c "$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio/master/scripts/get-platformio.py)" + - pip install -U platformio - # Libraries from PlatformIO Library Registry + # + # Libraries from PlatformIO Library Registry: + # # http://platformio.org/#!/lib/show/416/TinyGPS # http://platformio.org/#!/lib/show/417/SPI4Teensy3 - platformio lib install 416 417