From 0eff33dcbac65f57b72d683001d7bd2dd878d739 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Fri, 26 Jul 2019 17:57:49 +0200 Subject: [PATCH 01/12] first draft --- .gitignore | 1 + .goreleaser.yml | 90 ++++++++++++++++++++++++++++++++++ Dockerfiles/builder/Dockerfile | 24 +++++++++ 3 files changed, 115 insertions(+) create mode 100644 .goreleaser.yml create mode 100644 Dockerfiles/builder/Dockerfile diff --git a/.gitignore b/.gitignore index a3924579657..20441aa155e 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,4 @@ coverage_*.txt __pycache__ venv .pytest_cache +/dist \ No newline at end of file diff --git a/.goreleaser.yml b/.goreleaser.yml new file mode 100644 index 00000000000..d53cd92a8e9 --- /dev/null +++ b/.goreleaser.yml @@ -0,0 +1,90 @@ +# Global section +env: + - CGO_ENABLED=1 +checksum: + name_template: 'checksums.txt' + +snapshot: + name_template: "{{ .Tag }}-next" + +changelog: + sort: asc + filters: + exclude: + - '^[skip changelog]' + +# We have multiple builds in order to fine tune +# cross compilations. +builds: + - + # OSX + id: arduino_cli_osx + binary: arduino-cli + env: + - CC=o64-clang + goos: + - darwin + goarch: + - amd64 + ldflags: + - -s -w -X github.com/arduino/arduino-cli/version.versionString={{.Tag}} -X github.com/arduino/arduino-cli/version.commit=={{ .ShortCommit }} + - + # ARM + id: arduino_cli_arm + binary: arduino-cli + env: + - CC=arm-linux-gnueabihf-gcc + goos: + - linux + goarch: + - arm + goarm: + - 7 + ldflags: + - -s -w -X github.com/arduino/arduino-cli/version.versionString={{.Tag}} -X github.com/arduino/arduino-cli/version.commit=={{ .ShortCommit }} + - "-extldflags '-static'" + - + # ARM64 + id: arduino_cli_arm64 + binary: arduino-cli + env: + - CC=aarch64-linux-gnu-gcc + goos: + - linux + goarch: + - arm64 + ldflags: + - -s -w -X github.com/arduino/arduino-cli/version.versionString={{.Tag}} -X github.com/arduino/arduino-cli/version.commit=={{ .ShortCommit }} + - "-extldflags '-static'" + - + # All the other platforms + id: arduino_cli + binary: arduino-cli + goos: + - linux + - windows + goarch: + - amd64 + - 386 + ldflags: + - -s -w -X github.com/arduino/arduino-cli/version.versionString={{.Tag}} -X github.com/arduino/arduino-cli/version.commit=={{ .ShortCommit }} + - "-extldflags '-static'" + +archives: + - + id: "arduino_cli" + format: tar.gz + format_overrides: + - goos: windows + format: zip + replacements: + amd64: 64bit + darwin: macOS + 386: 32bit + arm: ARM + arm64: ARM64 + linux: Linux + windows: Windows + files: + - README.md + - LICENSE.txt diff --git a/Dockerfiles/builder/Dockerfile b/Dockerfiles/builder/Dockerfile new file mode 100644 index 00000000000..54527aa1883 --- /dev/null +++ b/Dockerfiles/builder/Dockerfile @@ -0,0 +1,24 @@ +FROM dockercore/golang-cross + +# Couldn't fine a more elegant way to fix this +RUN ln -s /usr/include/asm-generic /usr/include/asm + +RUN set -ex \ + && apt-get update -qq \ + && apt-get install -y -q --no-install-recommends \ + g++-multilib + +# Run in a different step to ease dependencies resolution +RUN set -ex \ + && apt-get install -y -q --no-install-recommends \ + gcc-aarch64-linux-gnu \ + gcc-arm-linux-gnueabihf + +# Install goreleaser +ENV GORELEASER_VER 0.113.0 +ENV GORELEASER_SHA 2379beebb6369b75ccead7f7a43269de700b51821feae3857701d106ed72bd63 +RUN set -ex \ + && curl -o goreleaser.tar.gz -LO https://github.com/goreleaser/goreleaser/releases/download/v${GORELEASER_VER}/goreleaser_Linux_x86_64.tar.gz \ + && echo "$GORELEASER_SHA goreleaser.tar.gz" | sha256sum -c - || exit 1 \ + && tar -xzf goreleaser.tar.gz -C /usr/bin/ goreleaser \ + && rm goreleaser.tar.gz From d32ebcb50e31d730413c866c6562c2b2a2abd601 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Mon, 29 Jul 2019 09:51:40 +0200 Subject: [PATCH 02/12] use crossbuild as base image --- .goreleaser.yml | 14 +++++++++----- Dockerfiles/builder/Dockerfile | 24 ++++++++---------------- 2 files changed, 17 insertions(+), 21 deletions(-) diff --git a/.goreleaser.yml b/.goreleaser.yml index d53cd92a8e9..c7f347eef8a 100644 --- a/.goreleaser.yml +++ b/.goreleaser.yml @@ -1,6 +1,4 @@ # Global section -env: - - CGO_ENABLED=1 checksum: name_template: 'checksums.txt' @@ -21,7 +19,9 @@ builds: id: arduino_cli_osx binary: arduino-cli env: - - CC=o64-clang + - CGO_ENABLED=1 + - CXXFLAGS="-mmacosx-version-min=10.10" + - CC=/usr/x86_64-apple-darwin14/bin/cc goos: - darwin goarch: @@ -33,7 +33,8 @@ builds: id: arduino_cli_arm binary: arduino-cli env: - - CC=arm-linux-gnueabihf-gcc + - CGO_ENABLED=1 + - CC=/usr/arm-linux-gnueabihf/bin/cc goos: - linux goarch: @@ -48,7 +49,8 @@ builds: id: arduino_cli_arm64 binary: arduino-cli env: - - CC=aarch64-linux-gnu-gcc + - CGO_ENABLED=1 + - CC=/usr/aarch64-linux-gnu/bin/cc goos: - linux goarch: @@ -60,6 +62,8 @@ builds: # All the other platforms id: arduino_cli binary: arduino-cli + env: + - CGO_ENABLED=0 goos: - linux - windows diff --git a/Dockerfiles/builder/Dockerfile b/Dockerfiles/builder/Dockerfile index 54527aa1883..5cd2eda5018 100644 --- a/Dockerfiles/builder/Dockerfile +++ b/Dockerfiles/builder/Dockerfile @@ -1,24 +1,16 @@ -FROM dockercore/golang-cross +FROM multiarch/crossbuild -# Couldn't fine a more elegant way to fix this -RUN ln -s /usr/include/asm-generic /usr/include/asm +ENV PATH $PATH:/usr/local/go/bin -RUN set -ex \ - && apt-get update -qq \ - && apt-get install -y -q --no-install-recommends \ - g++-multilib - -# Run in a different step to ease dependencies resolution -RUN set -ex \ - && apt-get install -y -q --no-install-recommends \ - gcc-aarch64-linux-gnu \ - gcc-arm-linux-gnueabihf - -# Install goreleaser +# Install tooling ENV GORELEASER_VER 0.113.0 ENV GORELEASER_SHA 2379beebb6369b75ccead7f7a43269de700b51821feae3857701d106ed72bd63 +ENV GOVER 1.12.7 RUN set -ex \ && curl -o goreleaser.tar.gz -LO https://github.com/goreleaser/goreleaser/releases/download/v${GORELEASER_VER}/goreleaser_Linux_x86_64.tar.gz \ && echo "$GORELEASER_SHA goreleaser.tar.gz" | sha256sum -c - || exit 1 \ && tar -xzf goreleaser.tar.gz -C /usr/bin/ goreleaser \ - && rm goreleaser.tar.gz + && rm goreleaser.tar.gz \ + && curl -LO https://dl.google.com/go/go${GOVER}.linux-amd64.tar.gz \ + && tar -C /usr/local -xzf go${GOVER}.linux-amd64.tar.gz \ + && rm go${GOVER}.linux-amd64.tar.gz From c26058d1d0465937fb629c65c23bbbc32a01d130 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Mon, 29 Jul 2019 10:26:15 +0200 Subject: [PATCH 03/12] add drone step --- .drone.yml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.drone.yml b/.drone.yml index cff5f148797..bf8dfe919ba 100644 --- a/.drone.yml +++ b/.drone.yml @@ -43,3 +43,12 @@ steps: - master event: - push + +- name: release + image: arduino/arduino-cli:builder-1.0 + commands: + # FIXME: run the real options + - goreleaser --snapshot --skip-publish --skip-validation + when: + ref: + - refs/tags/v* \ No newline at end of file From b3a8cfe2048cc3e654801329307f751981117c8f Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Mon, 29 Jul 2019 14:56:58 +0200 Subject: [PATCH 04/12] gix image name and build condition --- .drone.yml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.drone.yml b/.drone.yml index bf8dfe919ba..7462228b23a 100644 --- a/.drone.yml +++ b/.drone.yml @@ -45,10 +45,11 @@ steps: - push - name: release - image: arduino/arduino-cli:builder-1.0 + image: arduino/arduino-cli:builder-0.1 commands: # FIXME: run the real options - goreleaser --snapshot --skip-publish --skip-validation when: - ref: - - refs/tags/v* \ No newline at end of file + event: + - push + - tag \ No newline at end of file From 850e7ea58902b3c07c988b8e879828774b97ae7a Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Mon, 29 Jul 2019 15:38:09 +0200 Subject: [PATCH 05/12] split pipelines --- .drone.yml | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/.drone.yml b/.drone.yml index 7462228b23a..7911a933580 100644 --- a/.drone.yml +++ b/.drone.yml @@ -1,5 +1,6 @@ +--- kind: pipeline -name: default +name: test steps: - name: lint @@ -44,12 +45,25 @@ steps: event: - push +--- +kind: pipeline +name: release + +steps: +name: test - name: release image: arduino/arduino-cli:builder-0.1 + environment: + GITHUB_TOKEN: + from_secret: github_token commands: - # FIXME: run the real options - - goreleaser --snapshot --skip-publish --skip-validation - when: - event: - - push - - tag \ No newline at end of file + - goreleaser + +trigger: + event: + - tag + status: + - success + +depends_on: + - test \ No newline at end of file From a36e350258bd9b432a4e0c1b60a0f0a9468c88a4 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Mon, 29 Jul 2019 16:19:54 +0200 Subject: [PATCH 06/12] fix typo --- .drone.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.drone.yml b/.drone.yml index 7911a933580..6406a8012bf 100644 --- a/.drone.yml +++ b/.drone.yml @@ -50,7 +50,6 @@ kind: pipeline name: release steps: -name: test - name: release image: arduino/arduino-cli:builder-0.1 environment: From f5b6c24d4592a7179eca321005854ae06304b0f0 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Mon, 29 Jul 2019 18:56:02 +0200 Subject: [PATCH 07/12] add how to contribute --- CONTRIBUTING.md | 142 ++++++++++++++++++++++++++++++++++++ README.md | 186 +++++++++++++++++++++++------------------------- 2 files changed, 232 insertions(+), 96 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..25d30ee2312 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,142 @@ +# How to contribute + +First of all, thanks for contributing! + +This document provides some basic guidelines for contributing to this repository. To propose +improvements or fix a bug, feel free to submit a PR. + +## Legal requirements + +Before we can accept your contributions you have to sign the [Contributor License Agreement][0] + +## Prerequisites + +To build the Arduino CLI from sources you need the following tools to be available in your local +enviroment: + +* [Go][1] version 1.12 or later +* [Taskfile][2] to help you run the most common tasks from the command line + +If you want to run integration tests you will also need: + +* A serial port with an Arduino device attached +* A working [Python][3] environment, version 3.5 or later + +## Building the source code + +From the project folder root, just run: + +```shell +task build +``` + +The project uses Go modules so dependencies will be downloaded automatically, you should end with +an `arduino-cli` executable in the same folder. + +## Running the tests + +There are several checks and test suites in place to ensure the code works as expected but also it +is written in a way that's consistent across the whole codebase. Such tests can be run one after +another by running the command: + +```shell +task test +``` + +If you want to only run unit tests and skip other checks, you can run: + +```shell +task test-unit +``` + +Similarly, if you're only interested in running integration tests, you can do (be sure to read the +part dedicated to integration tests if something doesn't work): + +```shell +task test-integration +``` + +### Integration tests + +Being a command line interface, Arduino CLI is heavily interactive and it has to stay consistent +in accepting the user input and providing the expected output and proper exit codes. On top of this, +many Arduino CLI features involve communicating with external devices, most likely through a serial +port, so unit tests can only put our confidence that the code is working so far. + +For these reasons, in addition to regular unit tests the project has a suite of integration tests +that actually run Arduino CLI in a different process and assess the options are correctly +understood and the output is what we expect. + +To run the full suite of integration tests you need an Arduino device attached to a serial port and +a working Python environment. Chances are that you already have Python installed in your system, if +this is not the case you can [download][3] the official distribution or use the package manager +provided by your Operating System. + +Some dependencies need to be installed before running the tests and to avoid polluting your global +Python enviroment with dependencies that might be only used by the Arduino CLI, you can use a +[virtual environment][4]. There are many ways to manage virtual environments, for example you can +use a productivity tool called [hatch][5]. First you need to install it (you might need to `sudo` +the following command): + +```shell +pip3 install --user hatch +``` + +Then you can create a virtual environment to be used while working on Arduino CLI: + +```shell +hatch env arduino-cli +``` + +At this point the virtual environment was created and you need to make it active every time you +open a new terminal session with the following command: + +```shell +hatch shell arduino-cli +``` + +From now on, every package installed by Python will be confined to the `arduino-cli` virtual +environment, so you can proceed installing the dependencies required with: + +```shell +pip install -r test/requirements.txt +``` + +If the last step was successfull, you should be able to run the tests with: + +```shell +task test-integration +``` + +## Pull Requests + +In order to ease code reviews and have your contributions merged faster, here is a list of items +you can check before submitting a PR: + +* Create small PRs that are narrowly focused on addressing a single concern. +* PR titles indirectly become part of the CHANGELOG so it's crucial to provide a good + record of **what** change is being made in the title; **why** it was made will go in the + PR description, along with a link to a GitHub issue if it exists. +* write tests for the code you wrote. +* open your PR against the `master` branch. +* Maintain **clean commit history** and use **meaningful commit messages**. + PRs with messy commit history are difficult to review and require a lot of work to be merged. +* Your PR must pass all CI tests before we will merge it. If you're seeing an error and don't think + it's your fault, it may not be! The reviewer will help you if there are test failures that seem + not related to the change you are making. + +## Additional settings + +If you need to push a commit that's only shipping documentation changes or example files, thus a +complete no-op for the test suite, please start the commit message with the string **[skip ci]** +to skip the build and give that slot to someone else who does need it. + +If your PR doesn't need to be included in the changelog, please start the PR title with the string +**[skip changelog]** + +[0]: https://cla-assistant.io/arduino/arduino-cli +[1]: https://golang.org/doc/install +[2]: https://taskfile.dev/#/installation +[3]: https://www.python.org/downloads/ +[4]: https://docs.python.org/3/tutorial/venv.html +[5]: https://github.com/ofek/hatch diff --git a/README.md b/README.md index 0a3ecf0a2bb..fd53dc1e67a 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,20 @@ [![Build Status](https://cloud.drone.io/api/badges/arduino/arduino-cli/status.svg)](https://cloud.drone.io/arduino/arduino-cli) -`arduino-cli` is an all-in-one solution that provides builder, boards/library manager, uploader, discovery and many other tools needed to use any Arduino compatible board and platforms. +`arduino-cli` is an all-in-one solution that provides builder, boards/library manager, uploader, +discovery and many other tools needed to use any Arduino compatible board and platforms. This software is currently in alpha state: new features will be added and some may be changed. It will be soon used as a building block in the Arduino IDE and Arduino Create. +## How to contribute + +Contributions are welcome! + +Please read the document [How to contribute](CONTRIBUTING.md) which will guide you through how to +build the source code, run the tests, and contribute your changes to the project. + ## How to install ### Download the latest stable release @@ -16,8 +24,8 @@ This is **not yet available** until the first stable version is released. #### Download the latest unstable "alpha" preview -Please note that these are **preview** build, they may have bugs, some features may not work or may be changed without notice, -the latest preview version is `0.3.7-alpha.preview`: +Please note that these are **preview** builds, they may have bugs, some features may not work or may +be changed without notice, the latest preview version is `0.3.7-alpha.preview`: - [Linux 64 bit](https://downloads.arduino.cc/arduino-cli/arduino-cli-latest-linux64.tar.bz2) - [Linux 32 bit](https://downloads.arduino.cc/arduino-cli/arduino-cli-latest-linux32.tar.bz2) @@ -26,7 +34,8 @@ the latest preview version is `0.3.7-alpha.preview`: - [Windows](https://downloads.arduino.cc/arduino-cli/arduino-cli-latest-windows.zip) - [Mac OSX](https://downloads.arduino.cc/arduino-cli/arduino-cli-latest-macosx.zip) -Once downloaded, place the executable `arduino-cli` into a directory which is in your `PATH` environment variable. +Once downloaded, place the executable `arduino-cli` into a directory which is in your `PATH` +environment variable. #### Download the nightly build @@ -39,7 +48,8 @@ These builds are generated once a day from `master` branch starting at 23:00 UTC - [Windows](https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli-nightly-latest-windows.zip) - [Mac OSX](https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli-nightly-latest-macosx.zip) -Once downloaded, place the executable `arduino-cli` into a directory which is in your `PATH` environment variable. +Once downloaded, place the executable `arduino-cli` into a directory which is in your `PATH` +environment variable. ### Build the latest "bleeding-edge" from source @@ -52,8 +62,9 @@ You may want to copy the executable into a directory which is in your `PATH` env ## Usage -The goal of the Arduino CLI is to be used by either including it in Makefile or in any kind of script for the Command Line. -The Arduino CLI aims to replace the majority of features the Arduino IDE has without the graphical UI. +The goal of the Arduino CLI is to be used by either including it in Makefile or in any kind of +script for the Command Line. The Arduino CLI aims to replace the majority of features the Arduino +IDE has without the graphical UI. ## Getting Started @@ -89,22 +100,26 @@ and change the file to look like this one: ### Step 3. Connect the board to your PC -If you are running a fresh install of the arduino-cli you probably need to update the platform indexes by running: +If you are running a fresh install of the arduino-cli you probably need to update the platform +indexes by running: $ arduino-cli core update-index Updating index: package_index.json downloaded -Now, just connect the board to your PCs by using the USB cable. In this example we will use the MKR1000 board. +Now, just connect the board to your PCs by using the USB cable. In this example we will use the +MKR1000 board: $ arduino-cli board list FQBN Port ID Board Name /dev/ttyACM0 2341:804E unknown -the board has been discovered but we do not have the correct core to program it yet. Let's install it! +the board has been discovered but we do not have the correct core to program it yet. +Let's install it! ### Step 4. Find and install the right core -We have to look at the core available with the `core search` command. It will provide a list of available cores matching the name arduino +We have to look at the core available with the `core search` command. It will provide a list of +available cores matching the name arduino: $ arduino-cli core search arduino Searching for platforms matching 'arduino' @@ -165,13 +180,13 @@ If the board is not detected for any reason, you can list all the supported boar with `arduino-cli board listall` and also search for a specific board: $ arduino-cli board listall mkr - Board Name FQBN - Arduino MKR FOX 1200 arduino:samd:mkrfox1200 - Arduino MKR GSM 1400 arduino:samd:mkrgsm1400 - Arduino MKR WAN 1300 arduino:samd:mkrwan1300 - Arduino MKR WiFi 1010 arduino:samd:mkrwifi1010 - Arduino MKRZERO arduino:samd:mkrzero - Arduino/Genuino MKR1000 arduino:samd:mkr1000 + Board Name FQBN + Arduino MKR FOX 1200 arduino:samd:mkrfox1200 + Arduino MKR GSM 1400 arduino:samd:mkrgsm1400 + Arduino MKR WAN 1300 arduino:samd:mkrwan1300 + Arduino MKR WiFi 1010 arduino:samd:mkrwifi1010 + Arduino MKRZERO arduino:samd:mkrzero + Arduino/Genuino MKR1000 arduino:samd:mkr1000 Great! Now we have the Board FQBN (Fully Qualified Board Name) `arduino:samd:mkr1000` and the Board Name look good, we are ready to compile and upload the sketch @@ -193,14 +208,16 @@ And then run: ### Step 5. Compile the sketch -To compile the sketch we have to run the `compile` command with the proper FQBN we just got in the previous command. +To compile the sketch we have to run the `compile` command with the proper FQBN we just got in the +previous command. $ arduino-cli compile --fqbn arduino:samd:mkr1000 Arduino/MyFirstSketch Sketch uses 9600 bytes (3%) of program storage space. Maximum is 262144 bytes. ### Step 6. Upload your sketch -We can finally upload the sketch and see our board blinking, we now have to specify the serial port used by our board other than the FQBN: +We can finally upload the sketch and see our board blinking, we now have to specify the serial port +used by our board other than the FQBN: $ arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:samd:mkr1000 Arduino/MyFirstSketch No new serial port detected. @@ -236,7 +253,8 @@ We can finally upload the sketch and see our board blinking, we now have to spec ### Step 7. Add libraries -Now we can try to add a useful library to our sketch. We can at first look at the name of a library, our favourite one is the wifi101, here the command to get more info +Now we can try to add a useful library to our sketch. We can at first look at the name of a library, +our favourite one is the wifi101, here the command to get more info: $ arduino-cli lib search wifi101 Name: "WiFi101OTA" @@ -260,7 +278,8 @@ Now we can try to add a useful library to our sketch. We can at first look at th Types: Arduino Versions: [0.5.0, 0.6.0, 0.10.0, 0.11.0, 0.11.1, 0.11.2, 0.12.0, 0.15.2, 0.8.0, 0.9.0, 0.12.1, 0.14.1, 0.14.4, 0.14.5, 0.15.1, 0.7.0, 0.14.0, 0.14.2, 0.14.3, 0.9.1, 0.13.0, 0.15.0, 0.5.1] -We are now ready to install it! Please be sure to use the full name of the lib as specified in the "Name:" section previously seen +We are now ready to install it! Please be sure to use the full name of the lib as specified in the +"Name:" section previously seen: $ arduino-cli lib install "WiFi101" Downloading libraries... @@ -271,110 +290,85 @@ We are now ready to install it! Please be sure to use the full name of the lib a `arduino-cli` is a container of commands, to see the full list just run: -```bash -$ arduino-cli -Arduino Command Line Interface (arduino-cli). - -Usage: - arduino-cli [command] - -Examples: -arduino [flags...] - -Available Commands: - board Arduino board commands. - compile Compiles Arduino sketches. - config Arduino Configuration Commands. - core Arduino Core operations. - help Help about any command - lib Arduino commands about libraries. - sketch Arduino CLI Sketch Commands. - upload Upload Arduino sketches. - version Shows version number of Arduino CLI. -.... -``` + $ arduino-cli + Arduino Command Line Interface (arduino-cli). -Each command has his own specific help that can be obtained with the `help` command, for example: + Usage: + arduino-cli [command] -```bash -$ arduino-cli help core -Arduino Core operations. + Examples: + arduino [flags...] + + Available Commands: + board Arduino board commands. + compile Compiles Arduino sketches. + config Arduino Configuration Commands. + core Arduino Core operations. + help Help about any command + lib Arduino commands about libraries. + sketch Arduino CLI Sketch Commands. + upload Upload Arduino sketches. + version Shows version number of Arduino CLI. + .... + +Each command has his own specific help that can be obtained with the `help` command, for example: -Usage: - arduino-cli core [command] + $ arduino-cli help core + Arduino Core operations. -Examples: -arduino-cli core update-index # to update the package index file. + Usage: + arduino-cli core [command] -Available Commands: - download Downloads one or more cores and corresponding tool dependencies. - install Installs one or more cores and corresponding tool dependencies. - list Shows the list of installed cores. - update-index Updates the index of cores. + Examples: + arduino-cli core update-index # to update the package index file. -Flags: - -h, --help help for core + Available Commands: + download Downloads one or more cores and corresponding tool dependencies. + install Installs one or more cores and corresponding tool dependencies. + list Shows the list of installed cores. + update-index Updates the index of cores. -Global Flags: - --config-file string The custom config file (if not specified the default one will be used). - --debug Enables debug output (super verbose, used to debug the CLI). - --format string The output format, can be [text|json]. (default "text") + Flags: + -h, --help help for core -Use "arduino-cli core [command] --help" for more information about a command. + Global Flags: + --config-file string The custom config file (if not specified the default one will be used). + --debug Enables debug output (super verbose, used to debug the CLI). + --format string The output format, can be [text|json]. (default "text") -``` + Use "arduino-cli core [command] --help" for more information about a command. -# FAQ +## FAQ -#### Why the Arduino Uno/Mega/Duemilanove is not detected when I run `arduino-cli board list`? +### Why the Arduino Uno/Mega/Duemilanove is not detected when I run `arduino-cli board list`? Because: - Your board is a cheaper clone, or -- It mounts a USB2Serial converter like FT232 or CH320: these chips always reports the same USB VID/PID to the operating system, so the only thing that we know is that the board mounts that specific USB2Serial chip, but we don't know which board is. +- It mounts a USB2Serial converter like FT232 or CH320: these chips always reports the same USB +VID/PID to the operating system, so the only thing that we know is that the board mounts that +specific USB2Serial chip, but we don't know which board is. -#### What is the core for the Uno/Mega/Nano/Duemilanove? +### What is the core for the Uno/Mega/Nano/Duemilanove? `arduino:avr` -#### What is the FQBN for ...? +### What is the FQBN for ...? - Arduino UNO: `arduino:avr:uno` - Arduino Mega: `arduino:avr:mega` - Arduino Nano: `arduino:avr:nano` or `arduino:avr:nano:cpu=atmega328old` if you have the old bootloader -#### How can I find the core/FQBN for a board? +### How can I find the core/FQBN for a board? Update the core index to have latest boards informations: $ arduino-cli core update-index Updating index: package_index.json downloaded -See: https://github.com/arduino/arduino-cli#step-4-find-and-install-the-right-core +See: Further help can be found in [this comment](https://github.com/arduino/arduino-cli/issues/138#issuecomment-459169051) in [#138](https://github.com/arduino/arduino-cli/issues/138). -For a deeper understanding of how FQBN works, you should understand Arduino Hardware specification. You can find more information in this [arduino/Arduino wiki page](https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5-3rd-party-Hardware-specification) - -# Testing - -Currently Unit and Integration test are available for launch in 2 ways: - -1. classic `go test ./...` to launch both unit and integration test - -2. via [task](https://taskfile.dev) that includes the following options: - -``` -* build: Build the project -* check: Check fmt and lint, `legacy` will be skipped -* check-legacy: Check fmt and lint for the `legacy` package -* protoc: Compile protobuf definitions -* rpc-client: Run the rpc client test routine (server must be already started) -* test: Run the full testsuite, `legacy` will be skipped -* test-integration: Run integration tests only -* test-legacy: Run tests for the `legacy` package -* test-unit: Run unit tests only -* test-unit-race: Run unit tests only with race condition detection -``` - -For Example to launch unit tests only run: `task test-unit` +For a deeper understanding of how FQBN works, you should understand Arduino Hardware specification. +You can find more information in this [arduino/Arduino wiki page](https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5-3rd-party-Hardware-specification) From 43776e3522352494bcbe588eeee012a3f0241b0c Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Tue, 30 Jul 2019 10:28:40 +0200 Subject: [PATCH 08/12] fetch tags --- .drone.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.drone.yml b/.drone.yml index 6406a8012bf..5e7443ff9ab 100644 --- a/.drone.yml +++ b/.drone.yml @@ -50,6 +50,11 @@ kind: pipeline name: release steps: +- name: fetch + image: docker:git + commands: + - git fetch --tags + - name: release image: arduino/arduino-cli:builder-0.1 environment: From 69338e069c83caae864f9b6f21b237c9c2591aad Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Tue, 30 Jul 2019 10:54:13 +0200 Subject: [PATCH 09/12] exclude known tags --- .drone.yml | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/.drone.yml b/.drone.yml index 5e7443ff9ab..36b97ec2249 100644 --- a/.drone.yml +++ b/.drone.yml @@ -8,7 +8,7 @@ steps: commands: # Check if the Go code is properly formatted and run the linter - task check - # Ensure protobufs compile + # Ensure protobufs compile without errors - task protoc - name: build @@ -28,10 +28,10 @@ steps: - pip install -r test/requirements.txt - task test-integration -# Contrary to other CI platforms, uploading reports to Codecov requires Drone to provide a token. -# To avoid exposing the Codecov token to external PRs, we only upload coverage when we merge on -# `master`. - name: coverage + # Contrary to other CI platforms, uploading reports to Codecov requires Drone to provide a token. + # To avoid exposing the Codecov token to external PRs, we only upload coverage when we merge on + # `master`. image: arduino/arduino-cli:drone-1.0 environment: CODECOV_TOKEN: @@ -51,6 +51,7 @@ name: release steps: - name: fetch + # extra step needed to fetch tags after cloning image: docker:git commands: - git fetch --tags @@ -65,9 +66,16 @@ steps: trigger: event: + # releases are triggered by tags only - tag status: + # skip the release if the previous build failed - success + ref: + exclude: + # exclude the tags used to build Docker images for drone + - refs/tags/builder-* + - refs/tags/drone-* depends_on: - test \ No newline at end of file From 7839d4ffe6414fea42f907164693400e8ee93ef7 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Tue, 30 Jul 2019 11:49:57 +0200 Subject: [PATCH 10/12] Update CONTRIBUTING.md Co-Authored-By: per1234 --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 25d30ee2312..b3060957369 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -102,7 +102,7 @@ environment, so you can proceed installing the dependencies required with: pip install -r test/requirements.txt ``` -If the last step was successfull, you should be able to run the tests with: +If the last step was successful, you should be able to run the tests with: ```shell task test-integration From 5e3fd36bebe1667301f86ab7d70ca5112a63e140 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Tue, 30 Jul 2019 11:50:06 +0200 Subject: [PATCH 11/12] Update CONTRIBUTING.md Co-Authored-By: per1234 --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3060957369..4f2aac0dce1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -117,7 +117,7 @@ you can check before submitting a PR: * PR titles indirectly become part of the CHANGELOG so it's crucial to provide a good record of **what** change is being made in the title; **why** it was made will go in the PR description, along with a link to a GitHub issue if it exists. -* write tests for the code you wrote. +* Write tests for the code you wrote. * open your PR against the `master` branch. * Maintain **clean commit history** and use **meaningful commit messages**. PRs with messy commit history are difficult to review and require a lot of work to be merged. From 31403655870e475cd9100941b372259659fb02d0 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Tue, 30 Jul 2019 11:50:13 +0200 Subject: [PATCH 12/12] Update CONTRIBUTING.md Co-Authored-By: per1234 --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f2aac0dce1..7f7bf5ee39c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -118,7 +118,7 @@ you can check before submitting a PR: record of **what** change is being made in the title; **why** it was made will go in the PR description, along with a link to a GitHub issue if it exists. * Write tests for the code you wrote. -* open your PR against the `master` branch. +* Open your PR against the `master` branch. * Maintain **clean commit history** and use **meaningful commit messages**. PRs with messy commit history are difficult to review and require a lot of work to be merged. * Your PR must pass all CI tests before we will merge it. If you're seeing an error and don't think