# CircleCI

CircleCI is a hosted cloud platform that provides hosted continuous integration, deployment, and testing to GitHub repositories.

CircleCI is configured by adding a file named `circle.yml`, which is a YAML format text file, to the root directory of the GitHub repository.

CircleCI automatically detects when a commit has been made and pushed to a repository that is using CircleCI, and each time this happens, it will try to build the project using platformio ci command. This includes commits to all branches, not just to the master branch. CircleCI 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 Development Platforms.

Contents

- CircleCI

  - Integration

    - Using platformio run command

    - Using platformio ci command

      - Library dependencies

    - Install dependent library using Library Manager

    - Manually download dependent library and include in build process via `--lib` option

      - Custom Build Flags

      - Advanced configuration

  - Examples

## Integration

Note

Please make sure to read CircleCI Getting Started guide first.

There are two possible ways of running PlatformIO in CI services:

### Using platformio run command

This variant is default choice for native PlatformIO projects:

    dependencies:
        pre:
            # Install the latest stable PlatformIO
            - sudo pip install -U platformio

    test:
        override:
            - platformio run /path/to/project/dir -e <ID_1> -e <ID_2> -e <ID_N>

### Using platformio ci command

This variant is more convenient when project is written as a library (when there are examples or testing code) as it has additional options for specifying extra libraries and boards from command line interface:

    dependencies:
        pre:
            # Install the latest stable PlatformIO
            - sudo pip install -U platformio

    test:
        override:
            - platformio ci path/to/test/file.c --board=<ID_1> --board=<ID_2> --board=<ID_N>
            - platformio ci examples/file.ino --board=<ID_1> --board=<ID_2> --board=<ID_N>
            - platformio ci path/to/test/directory --board=<ID_1> --board=<ID_2> --board=<ID_N>

#### Library dependencies

There 2 options to test source code with dependent libraries:

### Install dependent library using Library Manager

    dependencies:
        pre:
            # Install the latest stable PlatformIO
            - sudo pip install -U platformio

            # OneWire Library with ID=1 https://platformio.org/lib/show/1/OneWire
            - platformio lib -g install 1

    test:
        override:
            - platformio ci path/to/test/file.c --board=<ID_1> --board=<ID_2> --board=<ID_N>

### Manually download dependent library and include in build process via `--lib` option

    dependencies:
        pre:
            # Install the latest stable PlatformIO
            - sudo 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/

    test:
        override:
            - platformio ci path/to/test/file.c --lib="/tmp/OneWire-master" --board=<ID_1> --board=<ID_2> --board=<ID_N>

#### Custom Build Flags

PlatformIO allows one to specify own build flags using `PLATFORMIO_BUILD_FLAGS` environment

    machine:
        environment:
            PLATFORMIO_BUILD_FLAGS: -D SPECIFIC_MACROS -I/extra/inc

For the more details, please follow to available build flags/options.

#### Advanced configuration

PlatformIO allows one to configure multiple build environments for the single source code using “platformio.ini” (Project Configuration File).

Instead of `--board` option, please use `platformio ci --project-conf`

    test:
        override:
            - platformio ci path/to/test/file.c --project-conf=/path/to/platoformio.ini

## Examples

1. Custom build flags

    dependencies:
        cache_directories:
            - "~/.platformio"

        pre:
            - sudo pip install -U platformio

            # pre-install PlatformIO development platforms, they will be cached
            - platformio platform install atmelavr atmelsam teensy

            #
            # Libraries from PlatformIO Library Registry:
            #
            # https://platformio.org/lib/show/416/TinyGPS
            # https://platformio.org/lib/show/417/SPI4Teensy3
            - platformio lib -g install 416 417

    test:
        override:
            - platformio ci examples/acm/acm_terminal --board=uno --board=teensy31 --board=due --lib="."
            - platformio ci examples/adk/adk_barcode --board=uno --board=teensy31 --board=due --lib="."
            - platformio ci examples/adk/ArduinoBlinkLED --board=uno --board=teensy31 --board=due --lib="."
            - platformio ci examples/adk/demokit_20 --board=uno --board=teensy31 --board=due --lib="."
            # ...
            - platformio ci examples/Xbox/XBOXUSB --board=uno --board=teensy31 --board=due --lib="."

2. Dependency on external libraries

    dependencies:
        pre:
            # Install the latest stable PlatformIO
            - sudo pip install -U platformio

            # download dependent libraries
            - wget https://github.com/jcw/jeelib/archive/master.zip -O /tmp/jeelib.zip
            - unzip /tmp/jeelib.zip -d /tmp

            - wget https://github.com/Rodot/Gamebuino/archive/master.zip  -O /tmp/gamebuino.zip
            - unzip /tmp/gamebuino.zip -d /tmp

    test:
        override:
            -  platformio ci examples/backSoon/backSoon.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
            -  platformio ci examples/etherNode/etherNode.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
            -  platformio ci examples/getDHCPandDNS/getDHCPandDNS.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
            -  platformio ci examples/getStaticIP/getStaticIP.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
            # ...
            -  platformio ci examples/twitter/twitter.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
            -  platformio ci examples/udpClientSendOnly/udpClientSendOnly.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
            -  platformio ci examples/udpListener/udpListener.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
            -  platformio ci examples/webClient/webClient.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560

- Configuration file: hhttps://github.com/ivankravets/ethercard/blob/master/circle.yaml

- Build History: https://circleci.com/gh/ivankravets/ethercard/tree/master