diff --git a/.dependabot/config.yml b/.dependabot/config.yml index 7ea78fd4044..a0a85a6ed61 100644 --- a/.dependabot/config.yml +++ b/.dependabot/config.yml @@ -7,4 +7,4 @@ update_configs: - match: update_type: "security" default_labels: - - "component/dependencies" \ No newline at end of file + - "component/dependencies" diff --git a/.editorconfig b/.editorconfig index 80cb4c9c445..13655934867 100644 --- a/.editorconfig +++ b/.editorconfig @@ -15,7 +15,7 @@ indent_size = 4 indent_style = space indent_size = 4 -[*.yml,*.tmpl] +[*.yml,*.yaml,*.tmpl] indent_style = space indent_size = 2 diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index c6a2a7f9634..f436714e036 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,21 +1,19 @@ --- name: 🐛 Bug Report about: If something isn't working as expected 🤔. - --- ## Bug Report ### Current behavior - + - ### Expected behavior - + ### Environment @@ -23,4 +21,5 @@ about: If something isn't working as expected 🤔. - OS and platform: ### Additional context + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 062db943f17..f6558462e19 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,31 +1,26 @@ **Please check if the PR fulfills these requirements** -- [ ] The PR has no duplicates (please search among the [Pull Requests](https://github.com/arduino/arduino-cli/pulls) before creating one) + +- [ ] The PR has no duplicates (please search among the [Pull Requests](https://github.com/arduino/arduino-cli/pulls) + before creating one) - [ ] The PR follows [our contributing guidelines](https://arduino.github.io/arduino-cli/CONTRIBUTING/#pull-requests) - [ ] Tests for the changes have been added (for bug fixes / features) - [ ] Docs have been added / updated (for bug fixes / features) - * **What kind of change does this PR introduce?** - -* **What is the current behavior?** +- **What is the current behavior?** - * **What is the new behavior?** - - -* **Does this PR introduce a breaking change?** +- **Does this PR introduce a breaking change?** - - * **Other information**: - --- + See [how to contribute](https://arduino.github.io/arduino-cli/CONTRIBUTING/) diff --git a/.github/workflows/arduino-stats.yaml b/.github/workflows/arduino-stats.yaml index cd793740009..d7812a2b707 100644 --- a/.github/workflows/arduino-stats.yaml +++ b/.github/workflows/arduino-stats.yaml @@ -3,7 +3,7 @@ name: arduino-stats on: schedule: # run every day at 12:30:00 - - cron: '30 12 * * *' + - cron: "30 12 * * *" jobs: push-stats: diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 895ee00c2e0..897fd98e944 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -4,27 +4,27 @@ on: pull_request: paths: # existing docs - - 'docs/**' + - "docs/**" # changes to the cli reference generator - - 'docsgen/**' + - "docsgen/**" # potential changes to commands documentation - - 'cli/**' + - "cli/**" # potential changes to gRPC documentation - - 'rpc/**' + - "rpc/**" # changes to the workflow itself - - '.github/workflows/docs.yaml' + - ".github/workflows/docs.yaml" push: branches: - master # release branches have names like 0.8.x, 0.9.x, ... - - '[0-9]+.[0-9]+.x' + - "[0-9]+.[0-9]+.x" # At this day, GitHub doesn't support YAML anchors, d'oh! paths: - - 'docs/**' - - 'docsgen/**' - - 'cli/**' - - 'rpc/**' - - '.github/workflows/docs.yaml' + - "docs/**" + - "docsgen/**" + - "cli/**" + - "rpc/**" + - ".github/workflows/docs.yaml" jobs: build: @@ -42,7 +42,7 @@ jobs: - name: Setup Go uses: actions/setup-go@v2-beta with: - go-version: '1.14' + go-version: "1.14" - name: Install Go dependencies run: | @@ -57,8 +57,8 @@ jobs: - name: Setup Python uses: actions/setup-python@v1 with: - python-version: '3.6' - architecture: 'x64' + python-version: "3.6" + architecture: "x64" - name: Cache dependencies uses: actions/cache@v1 diff --git a/.github/workflows/github-stats.yaml b/.github/workflows/github-stats.yaml index a78fe223e49..011fef3aaa8 100644 --- a/.github/workflows/github-stats.yaml +++ b/.github/workflows/github-stats.yaml @@ -3,7 +3,7 @@ name: github-stats on: schedule: # run every 30 minutes - - cron: '*/30 * * * *' + - cron: "*/30 * * * *" jobs: push-stats: diff --git a/.github/workflows/i18n-nightly-push.yaml b/.github/workflows/i18n-nightly-push.yaml index 85e60fefadc..9908f574bd3 100644 --- a/.github/workflows/i18n-nightly-push.yaml +++ b/.github/workflows/i18n-nightly-push.yaml @@ -3,7 +3,7 @@ name: i18n-nightly-push on: schedule: # run every day at 1AM - - cron: '0 1 * * *' + - cron: "0 1 * * *" jobs: push-to-transifex: @@ -15,7 +15,7 @@ jobs: - name: Install Go uses: actions/setup-go@v2 with: - go-version: '1.14' + go-version: "1.14" - name: Install Taskfile uses: Arduino/actions/setup-taskfile@master @@ -27,4 +27,4 @@ jobs: env: TRANSIFEX_PROJECT: ${{ secrets.TRANSIFEX_PROJECT }} TRANSIFEX_RESOURCE: ${{ secrets.TRANSIFEX_RESOURCE }} - TRANSIFEX_API_KEY: ${{ secrets.TRANSIFEX_API_KEY }} \ No newline at end of file + TRANSIFEX_API_KEY: ${{ secrets.TRANSIFEX_API_KEY }} diff --git a/.github/workflows/i18n-weekly-pull.yaml b/.github/workflows/i18n-weekly-pull.yaml index 06fd5c84e36..3b9e46320de 100644 --- a/.github/workflows/i18n-weekly-pull.yaml +++ b/.github/workflows/i18n-weekly-pull.yaml @@ -3,7 +3,7 @@ name: i18n-weekly-pull on: schedule: # run every monday at 2AM - - cron: '0 2 * * 1' + - cron: "0 2 * * 1" jobs: pull-from-transifex: @@ -15,7 +15,7 @@ jobs: - name: Install Go uses: actions/setup-go@v2 with: - go-version: '1.14' + go-version: "1.14" - name: Install Go deps run: | @@ -38,4 +38,4 @@ jobs: with: commit-message: Updated translation files title: Updated translation files - branch: i18n/translations-update \ No newline at end of file + branch: i18n/translations-update diff --git a/.github/workflows/nightly.yaml b/.github/workflows/nightly.yaml index 8eadff6ffe3..5bc38a5fe96 100644 --- a/.github/workflows/nightly.yaml +++ b/.github/workflows/nightly.yaml @@ -3,10 +3,9 @@ name: nightly on: schedule: # run every day at 1AM - - cron: '0 1 * * *' + - cron: "0 1 * * *" jobs: - create-nightly-artifacts: runs-on: ubuntu-latest @@ -94,9 +93,9 @@ jobs: - name: upload uses: docker://plugins/s3 env: - PLUGIN_SOURCE: 'dist/*' - PLUGIN_TARGET: '/arduino-cli/nightly' - PLUGIN_STRIP_PREFIX: 'dist/' + PLUGIN_SOURCE: "dist/*" + PLUGIN_TARGET: "/arduino-cli/nightly" + PLUGIN_STRIP_PREFIX: "dist/" PLUGIN_BUCKET: ${{ secrets.DOWNLOADS_BUCKET }} AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 4d7f39cf1be..85968612d9e 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -3,10 +3,9 @@ name: release on: push: tags: - - '[0-9]+.[0-9]+.[0-9]+*' + - "[0-9]+.[0-9]+.[0-9]+*" jobs: - create-release-artifacts: runs-on: ubuntu-latest @@ -134,9 +133,9 @@ jobs: - name: Upload release files on Arduino downloads servers uses: docker://plugins/s3 env: - PLUGIN_SOURCE: 'dist/*' - PLUGIN_TARGET: '/arduino-cli/' - PLUGIN_STRIP_PREFIX: 'dist/' + PLUGIN_SOURCE: "dist/*" + PLUGIN_TARGET: "/arduino-cli/" + PLUGIN_STRIP_PREFIX: "dist/" PLUGIN_BUCKET: ${{ secrets.DOWNLOADS_BUCKET }} AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} diff --git a/.github/workflows/stale.yaml b/.github/workflows/stale.yaml index d439cb0cf00..3b83f33b944 100644 --- a/.github/workflows/stale.yaml +++ b/.github/workflows/stale.yaml @@ -3,9 +3,9 @@ name: stale-bot on: schedule: # run every day at midnight - - cron: '0 0 * * *' + - cron: "0 0 * * *" issue_comment: - types: ['created'] + types: ["created"] jobs: stale-bot: diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index 0384f5ae4d5..d5b78c5f3f7 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -30,7 +30,7 @@ jobs: - name: Install Go uses: actions/setup-go@v2 with: - go-version: '1.14' + go-version: "1.14" - name: Install Go deps # Since 10/23/2019 pwsh is the default shell diff --git a/.github/workflows/verify-formatting.yaml b/.github/workflows/verify-formatting.yaml new file mode 100644 index 00000000000..b27658dff26 --- /dev/null +++ b/.github/workflows/verify-formatting.yaml @@ -0,0 +1,33 @@ +name: "Verify files formatting" + +on: + push: + paths: + - "**/*.md" + - "**/*.yml" + - "**/*.yaml" + - ".prettierrc" + - ".prettierignore" + pull_request: + paths: + - "**/*.md" + - "**/*.yml" + - "**/*.yaml" + - ".prettierrc" + - ".prettierignore" + +jobs: + verify-formatting: + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@master + + - name: Install Taskfile + uses: Arduino/actions/setup-taskfile@master + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + + - name: Verify formatting of all files + run: task docs:check config:check diff --git a/.goreleaser.yml b/.goreleaser.yml index e02897be7a6..fa0343cf799 100644 --- a/.goreleaser.yml +++ b/.goreleaser.yml @@ -19,8 +19,7 @@ changelog: # We have multiple builds in order to fine tune # cross compilations. builds: - - - # OSX + - # OSX id: arduino_cli_osx binary: arduino-cli env: @@ -33,8 +32,7 @@ builds: - amd64 ldflags: - -s -w -X github.com/arduino/arduino-cli/version.versionString={{.Tag}} -X github.com/arduino/arduino-cli/version.commit={{ .ShortCommit }} - - - # ARM + - # ARM id: arduino_cli_arm binary: arduino-cli env: @@ -49,8 +47,7 @@ builds: ldflags: - -s -w -X github.com/arduino/arduino-cli/version.versionString={{.Tag}} -X github.com/arduino/arduino-cli/version.commit={{ .ShortCommit }} - "-extldflags '-static'" - - - # ARMv7 + - # ARMv7 id: arduino_cli_armv7 binary: arduino-cli env: @@ -65,8 +62,7 @@ builds: ldflags: - -s -w -X github.com/arduino/arduino-cli/version.versionString={{.Tag}} -X github.com/arduino/arduino-cli/version.commit={{ .ShortCommit }} - "-extldflags '-static'" - - - # ARM64 + - # ARM64 id: arduino_cli_arm64 binary: arduino-cli env: @@ -79,8 +75,7 @@ builds: 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 + - # All the other platforms id: arduino_cli binary: arduino-cli env: @@ -96,8 +91,7 @@ builds: - "-extldflags '-static'" archives: - - - id: "arduino_cli" + - id: "arduino_cli" format: tar.gz format_overrides: - goos: windows diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 00000000000..6260782e4b0 --- /dev/null +++ b/.prettierignore @@ -0,0 +1,5 @@ +# IDE files +.idea/ +.vscode/ +.vs/ +.ionide/ diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 00000000000..2703167c8a0 --- /dev/null +++ b/.prettierrc @@ -0,0 +1,12 @@ +{ + "semi": false, + "printWidth": 120, + "overrides": [ + { + "files": "*.md", + "options": { + "proseWrap": "always" + } + } + ] +} diff --git a/README.md b/README.md index 54208a09452..bb3389ca0b5 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,16 @@ ![cli-logo](./docs/img/CLI_Logo_small.png) -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. [![tests-badge]](https://github.com/Arduino/arduino-cli/actions?workflow=test) [![nightly-badge]](https://github.com/Arduino/arduino-cli/actions?workflow=nightly) [![docs-badge]](https://github.com/Arduino/arduino-cli/actions?workflow=docs) [![codecov-badge]](https://codecov.io/gh/arduino/arduino-cli) -> **Note:** this software is currently under active development: anything can change - at any time, API and UI must be considered unstable until we release version 1.0.0. +> **Note:** this software is currently under active development: anything can change at any time, API and UI must be +> considered unstable until we release version 1.0.0. ## Docs @@ -29,29 +28,27 @@ For guidance on installation and development, see the [User documentation]. Contributions are welcome! -Please read the document [How to contribute] which will show you how to build -the source code, run the tests, and contribute your changes to the project. +Please read the document [How to contribute] which will show you how to build the source code, run the tests, and +contribute your changes to the project. :sparkles: Thanks to all our [contributors]! :sparkles: ## Security -If you think you found a vulnerability or other security-related bug in the -Arduino CLI, please read our [security policy] and report the bug to our -Security Team 🛡️ Thank you! +If you think you found a vulnerability or other security-related bug in the Arduino CLI, please read our [security +policy] and report the bug to our Security Team 🛡️ Thank you! e-mail contact: security@arduino.cc - [tests-badge]: https://github.com/Arduino/arduino-cli/workflows/test/badge.svg [nightly-badge]: https://github.com/Arduino/arduino-cli/workflows/nightly/badge.svg [docs-badge]: https://github.com/Arduino/arduino-cli/workflows/docs/badge.svg [codecov-badge]: https://codecov.io/gh/arduino/arduino-cli/branch/master/graph/badge.svg -[Install]: https://arduino.github.io/arduino-cli/installation -[User documentation]: https://arduino.github.io/arduino-cli/ -[Getting Started]: https://arduino.github.io/arduino-cli/getting-started/ -[Commands reference]: https://arduino.github.io/arduino-cli/commands/arduino-cli -[FAQ]: https://arduino.github.io/arduino-cli/FAQ/ -[How to contribute]: https://arduino.github.io/arduino-cli/CONTRIBUTING/ +[install]: https://arduino.github.io/arduino-cli/installation +[user documentation]: https://arduino.github.io/arduino-cli/ +[getting started]: https://arduino.github.io/arduino-cli/getting-started/ +[commands reference]: https://arduino.github.io/arduino-cli/commands/arduino-cli +[faq]: https://arduino.github.io/arduino-cli/FAQ/ +[how to contribute]: https://arduino.github.io/arduino-cli/CONTRIBUTING/ [contributors]: https://github.com/arduino/arduino-cli/graphs/contributors [security policy]: https://github.com/arduino/arduino-cli/security/policy diff --git a/Taskfile.yml b/Taskfile.yml index 6865ded6433..35564237461 100755 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -1,4 +1,4 @@ -version: '2' +version: "2" tasks: docs:gen:commands: @@ -49,6 +49,16 @@ tasks: cmds: - mkdocs serve + docs:check: + desc: Run documentation linting + cmds: + - npx {{ .PRETTIER }} --check "**/*.md" + + docs:format: + desc: Automatically formats documentation + cmds: + - npx {{ .PRETTIER }} --write "**/*.md" + protoc: desc: Compile protobuf definitions cmds: @@ -105,6 +115,18 @@ tasks: - "'{{.GOLINTBIN}}' {{.GOLINTFLAGS}} {{ default .DEFAULT_TARGETS .TARGETS }}" - task: i18n:check - task: python:check + - task: docs:check + - task: config:check + + config:check: + desc: Check linting of configuration and supporting files + cmds: + - npx {{ .PRETTIER }} --check "**/*.{yml,yaml}" + + config:format: + desc: Automatically formats configuration and supporting files + cmds: + - npx {{ .PRETTIER }} --write "**/*.{yml,yaml}" python:check: desc: Linting for Python files @@ -183,3 +205,4 @@ vars: DOCS_VERSION: dev DOCS_ALIAS: "" DOCS_REMOTE: "origin" + PRETTIER: prettier@2.0.5 diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index bbf2e35a7dc..e5261cb1d7a 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -2,8 +2,8 @@ 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. +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 @@ -11,42 +11,36 @@ Before we can accept your contributions you have to sign the [Contributor Licens ## 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: +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 +- 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. +- 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. ## Prerequisites -To build the Arduino CLI from sources you need the following tools to be -available in your local environment: +To build the Arduino CLI from sources you need the following tools to be available in your local environment: -* [Go][1] version 1.12 or later -* [Taskfile][2] to help you run the most common tasks from the command line +- [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 board attached -* A working [Python][3] environment, version 3.8 or later +- A serial port with an Arduino board attached +- A working [Python][3] environment, version 3.8 or later If you're working on the gRPC interface you will also have to: -* download the [protoc][6] compiler -* run `go get -u github.com/golang/protobuf/protoc-gen-go` +- download the [protoc][6] compiler +- run `go get -u github.com/golang/protobuf/protoc-gen-go` ## Building the source code @@ -56,15 +50,13 @@ From the project folder root, just run: task build ``` -The project uses Go modules so dependencies will be downloaded automatically; -at the end of the build, you should find an `arduino-cli` executable in the -same folder. +The project uses Go modules so dependencies will be downloaded automatically; at the end of the build, you should find +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 and is written in a way that's consistent across the whole codebase. -To avoid pushing changes that will cause the CI system to fail, you can run most +There are several checks and test suites in place to ensure the code works as expected and is written in a way that's +consistent across the whole codebase. To avoid pushing changes that will cause the CI system to fail, you can run most of the tests locally. To ensure code style is consistent, run: @@ -79,8 +71,7 @@ To run unit tests: task test-unit ``` -To run integration tests (these will take some time and require special setup, -see following paragraph): +To run integration tests (these will take some time and require special setup, see following paragraph): ```shell task test-integration @@ -88,14 +79,12 @@ task test-integration ### Running only some tests -By default, all tests from all go packages are run. To run only unit -tests from one or more specific packages, you can set the TARGETS -environment variable, e.g.: +By default, all tests from all go packages are run. To run only unit tests from one or more specific packages, you can +set the TARGETS environment variable, e.g.: TARGETS=./arduino/cores/packagemanager task test-unit -Alternatively, to run only some specific test(s), you can specify a regex -to match against the test function name: +Alternatively, to run only some specific test(s), you can specify a regex to match against the test function name: TEST_REGEX='^TestTryBuild.*' task test-unit @@ -105,40 +94,34 @@ Both can be combined as well, typically to run only a specific test: ### 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 go so far in giving us confidence that the code is -working. +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 go so far in giving us +confidence that the code is working. -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. +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. #### Hardware requirements for running the full suite of integration tests: An Arduino board attached to a serial port. The board must: -* Use one of the VID/PID pairs used by Arduino or their partners (as is the case -with all modern official Arduino boards except the classic Nano). -* Accept uploads using the FQBN associated with that VID/PID (which will be the -case unless you have installed a custom bootloader or removed the bootloader). +- Use one of the VID/PID pairs used by Arduino or their partners (as is the case with all modern official Arduino boards + except the classic Nano). +- Accept uploads using the FQBN associated with that VID/PID (which will be the case unless you have installed a custom + bootloader or removed the bootloader). -Note that running the integration tests will result in a sketch being uploaded -to every attached Arduino board meeting the above requirements. +Note that running the integration tests will result in a sketch being uploaded to every attached Arduino board meeting +the above requirements. #### Software requirements for running integration tests: -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. +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 environment with dependencies that might be only -used by the Arduino CLI, to do so we use [Poetry][poetry-website]. First you need to install it (you might need to `sudo` -the following command): +Some dependencies need to be installed before running the tests and to avoid polluting your global Python environment +with dependencies that might be only used by the Arduino CLI, to do so we use [Poetry][poetry-website]. First you need +to install it (you might need to `sudo` the following command): ```shell pip3 install --user poetry @@ -152,7 +135,8 @@ After Poetry has been installed you should be able to run the tests with: task test-integration ``` -This will automatically install the necessary dependencies, if not already installed, and run the integration tests automatically. +This will automatically install the necessary dependencies, if not already installed, and run the integration tests +automatically. When editing any Python file in the project remember to run linting checks with: @@ -160,7 +144,8 @@ When editing any Python file in the project remember to run linting checks with: task python:check ``` -This will run `flake8` automatically and return any error in the code formatting, if not already installed it will also install integration tests dependencies. +This will run `flake8` automatically and return any error in the code formatting, if not already installed it will also +install integration tests dependencies. In case of linting errors you should be able to solve most of them by automatically formatting with: @@ -168,114 +153,151 @@ In case of linting errors you should be able to solve most of them by automatica task python:format ``` +### Configuration files formatting + +To keep the configurations tidy and in order we use [Prettier][prettier-website] to automatically format all YAML files +in the project. Keeping and enforcing a formatting standard helps everyone make small PRs and avoids the introduction of +formatting changes made by unconfigured editors. + +There are several ways to run Prettier, if you're using Visual Studio Code you can easily use the [`prettier-vscode` +extension][prettier-vscode-extension] to automatically format as you write. + +Otherwise you can use the following tasks, to do so you'll need to install `npm` if not already installed. Check the +[official documentation][npm-install-docs] to know how to install `npm` for your platform. + +To check if the files are correctly formatted run: + +```shell +task config:check +``` + +If the output tells you that some files are not formatted correctly run: + +```shell +task config:format +``` + +When opening a new Pull Requests checks are automatically run to verify that configuration files are correctly +formatted. In case of failures we might ask you to update the PR with correct formatting. + ## Working on docs -Documentation is provided to final users in form of static HTML content generated -from a tool called [MkDocs][9] and hosted on [GitHub Pages][7]. +Documentation is provided to final users in form of static HTML content generated from a tool called [MkDocs][9] and +hosted on [GitHub Pages][7]. ### Local development -Most of the documentation consists of static content written over several -Markdown files under the `docs` folder at the root of this git repository but -some other content is dynamically generated from the CI pipelines - this is the -case with the command line reference and the gRPC interface, for example. +Most of the documentation consists of static content written over several Markdown files under the `docs` folder at the +root of this git repository but some other content is dynamically generated from the CI pipelines - this is the case +with the command line reference and the gRPC interface, for example. -If you want to check out how the documentation would look after some local -changes, you might need to reproduce what happens in the CI, generating the full -documentation website from your personal computer. To run the docs toolchain +If you want to check out how the documentation would look after some local changes, you might need to reproduce what +happens in the CI, generating the full documentation website from your personal computer. To run the docs toolchain locally, you need to have a few dependencies and tools installed: -* [Go][1] version 1.12 or later -* [Taskfile][2] to help you run the most common tasks from the command line -* A working [Python][3] environment, see [this paragraph](#integration-tests) - if you need to setup one +- [Go][1] version 1.12 or later +- [Taskfile][2] to help you run the most common tasks from the command line +- A working [Python][3] environment, see [this paragraph](#integration-tests) if you need to setup one -Before running the toolchain, perform the following operations from the root of -the git repository (if you have a Python virtual environment, activate it before -proceeding): +Before running the toolchain, perform the following operations from the root of the git repository (if you have a Python +virtual environment, activate it before proceeding): -* go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc -* pip install -r requirements_docs.txt +- go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc +- pip install -r requirements_docs.txt -When working on docs, you can launch a command that will take care of -generating the docs, build the static website and start a local server you can -later access with a web browser to see a preview of your changes. From the root -of the git repository run: +When working on docs, you can launch a command that will take care of generating the docs, build the static website and +start a local server you can later access with a web browser to see a preview of your changes. From the root of the git +repository run: ```shell task docs:serve ``` -If you don't see any error, hit http://127.0.0.1:8000 with your browser to -navigate the generated docs. +If you don't see any error, hit http://127.0.0.1:8000 with your browser to navigate the generated docs. ### Docs publishing -The present git repository has a special branch called `gh-pages` that contains -the generated HTML code for the docs website; every time a change is pushed to -this special branch, GitHub automatically triggers a [deployment][8] to pull the -change and publish a new version of the website. Do not open Pull Requests to -push changes to the `gh-pages` branch, that will be done exclusively from the -CI. +The present git repository has a special branch called `gh-pages` that contains the generated HTML code for the docs +website; every time a change is pushed to this special branch, GitHub automatically triggers a [deployment][8] to pull +the change and publish a new version of the website. Do not open Pull Requests to push changes to the `gh-pages` branch, +that will be done exclusively from the CI. ### Docs versioning -In order to provide support for multiple Arduino CLI releases, Documentation is -versioned so that visitors can select which version of the documentation website -should be displayed. Unfortunately this feature isn't provided by GitHub pages -or MkDocs, so we had to implement it on top of the generation process. - -Before delving into the details of the generation process, here follow some -requirements that were established to provide versioned documentation: - -* A special version of the documentation called `dev` is provided to reflect the - status of the Arduino CLI on the `master` branch - this includes unreleased - features and bugfixes. -* Docs are versioned after the minor version of an Arduino CLI release. For - example, Arduino CLI `0.99.1` and `0.99.2` will be both covered by - documentation version `0.99`. -* The landing page of the documentation website will automatically redirect - visitors to the most recently released version of the Arduino CLI. - -To implement the requirements above, the execution of MkDocs is wrapped using a -CLI tool called [Mike][10] that does a few things for us: - -* It runs MkDocs targeting subfolders named after the Arduino CLI version, e.g. - documentation for version `0.10.1` can be found under the folder `0.10`. -* It injects an HTML control into the documentation website that lets visitors - choose which version of the docs to browse from a dropdown list. -* It provides a redirect to a version we decide when visitors hit the landing - page of the documentation website. -* It pushes generated contents to the `gh-pages` branch. - -> **Note:** unless you're working on the generation process itself, you should -> never run Mike from a local environment, either directly or through the Task -> `docs:publish`. This might result in unwanted changes to the public website. +In order to provide support for multiple Arduino CLI releases, Documentation is versioned so that visitors can select +which version of the documentation website should be displayed. Unfortunately this feature isn't provided by GitHub +pages or MkDocs, so we had to implement it on top of the generation process. + +Before delving into the details of the generation process, here follow some requirements that were established to +provide versioned documentation: + +- A special version of the documentation called `dev` is provided to reflect the status of the Arduino CLI on the + `master` branch - this includes unreleased features and bugfixes. +- Docs are versioned after the minor version of an Arduino CLI release. For example, Arduino CLI `0.99.1` and `0.99.2` + will be both covered by documentation version `0.99`. +- The landing page of the documentation website will automatically redirect visitors to the most recently released + version of the Arduino CLI. + +To implement the requirements above, the execution of MkDocs is wrapped using a CLI tool called [Mike][10] that does a +few things for us: + +- It runs MkDocs targeting subfolders named after the Arduino CLI version, e.g. documentation for version `0.10.1` can + be found under the folder `0.10`. +- It injects an HTML control into the documentation website that lets visitors choose which version of the docs to + browse from a dropdown list. +- It provides a redirect to a version we decide when visitors hit the landing page of the documentation website. +- It pushes generated contents to the `gh-pages` branch. + +> **Note:** unless you're working on the generation process itself, you should never run Mike from a local environment, +> either directly or through the Task `docs:publish`. This might result in unwanted changes to the public website. + +### Docs formatting + +To keep the documentation tidy and in order we use [Prettier][prettier-website] to automatically format all Markdown +files in the project. Keeping and enforcing a formatting standard helps everyone make small PRs and avoids the +introduction of formatting changes made by unconfigured editors. + +There are several ways to run Prettier, if you're using Visual Studio Code you can easily use the [`prettier-vscode` +extension][prettier-vscode-extension] to automatically format as you write. + +Otherwise you can use the following tasks, to do so you'll need to install `npm` if not already installed. Check the +[official documentation][npm-install-docs] to know how to install `npm` for your platform. + +To check if the files are correctly formatted run: + +```shell +task docs:check +``` + +If the output tells you that some files are not formatted correctly run: + +```shell +task docs:format +``` + +When opening a new Pull Requests checks are automatically run to verify that documentation is correctly formatted. In +case of failures we might ask you to update the PR with correct formatting. ### Docs automation -In order to avoid unwanted changes to the public website hosting the Arduino -CLI documentation, only Mike is allowed to push changes to the `gh-pages` branch, -and this only happens from within the CI, in a workflow named [docs][11]. +In order to avoid unwanted changes to the public website hosting the Arduino CLI documentation, only Mike is allowed to +push changes to the `gh-pages` branch, and this only happens from within the CI, in a workflow named [docs][11]. -The CI is responsible for guessing which version of the Arduino CLI we're -building docs for, so that generated contents will be stored in the appropriate -section of the documentation website. Because this guessing might be fairly -complex, the logic is implemented in a Python script called [`build.py`][12]. -The script will determine the version of the Arduino CLI that was modified in -the current commit (either `dev` or an official, numbered release) and whether -the redirect to the latest version that happens on the landing page should be -updated or not. +The CI is responsible for guessing which version of the Arduino CLI we're building docs for, so that generated contents +will be stored in the appropriate section of the documentation website. Because this guessing might be fairly complex, +the logic is implemented in a Python script called [`build.py`][12]. The script will determine the version of the +Arduino CLI that was modified in the current commit (either `dev` or an official, numbered release) and whether the +redirect to the latest version that happens on the landing page should be updated or not. ## Internationalization (i18n) -In order to support i18n in the CLI, any messages that are intended to be translated -should be wrapped in a call to `i18n.Tr`. This call allows us to build a catalog of -translatable strings, replacing the reference string at runtime with the localized value. +In order to support i18n in the CLI, any messages that are intended to be translated should be wrapped in a call to +`i18n.Tr`. This call allows us to build a catalog of translatable strings, replacing the reference string at runtime +with the localized value. -Adding or modifying these messages requires an i18n update, as this process creates the -reference catalog that are shared with translators. For that reason, the `task check` -command will fail if the catalog was not updated to sync with changes to the source code. +Adding or modifying these messages requires an i18n update, as this process creates the reference catalog that are +shared with translators. For that reason, the `task check` command will fail if the catalog was not updated to sync with +changes to the source code. To update the catalog, execute the following command and commit the changes. @@ -306,13 +328,11 @@ func main() { ## 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 +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]** +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 @@ -327,3 +347,6 @@ title with the string **[skip changelog]** [10]: https://github.com/jimporter/mike [11]: https://github.com/arduino/arduino-cli/blob/master/.github/workflows/docs.yaml [12]: https://github.com/arduino/arduino-cli/blob/master/docs/build.py +[prettier-website]: https://prettier.io/ +[prettier-vscode-extension]: https://github.com/prettier/prettier-vscode +[npm-install-docs]: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm diff --git a/docs/FAQ.md b/docs/FAQ.md index 256dcd336d9..11202a6841b 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -2,18 +2,16 @@ When you run `arduino-cli board list`, your board doesn't show up. Possible causes: -- Your board is a cheaper clone, or -- It mounts a USB2Serial converter like FT232 or CH340: these chips - always report the same USB VID/PID to the operating system, so the - only thing we know is that the board mounts that specific - USB2Serial chip, but we don’t know which board that chip is on. +- Your board is a cheaper clone, or +- It mounts a USB2Serial converter like FT232 or CH340: these chips always report the same USB VID/PID to the operating + system, so the only thing we know is that the board mounts that specific USB2Serial chip, but we don’t know which + board that chip is on. -## What's the FQBN string? +## What's the FQBN string? -For a deeper understanding of how FQBN works, you should understand -the [Arduino platform specification][0]. +For a deeper understanding of how FQBN works, you should understand the [Arduino platform specification][0]. -## How to set multiple board options? +## How to set multiple board options? Additional board options have to be separated by commas (instead of colon): diff --git a/docs/command-line-completion.md b/docs/command-line-completion.md index 6535360144b..d7e8a2a8b1e 100644 --- a/docs/command-line-completion.md +++ b/docs/command-line-completion.md @@ -1,24 +1,30 @@ -`arduino-cli` supports command-line completion (also known as *tab completion*) for basic commands. -Currently only `bash`, `zsh`, `fish` shells are supported +`arduino-cli` supports command-line completion (also known as _tab completion_) for basic commands. Currently only +`bash`, `zsh`, `fish` shells are supported ### Before you start -In order to generate the file required to make the completion work you have to [install](installation.md) Arduino CLI first. + +In order to generate the file required to make the completion work you have to [install](installation.md) Arduino CLI +first. ### Generate the completion file -To generate the completion file you can use `arduino-cli completion [bash|zsh|fish] [--no-descriptions]`. -By default this command will print on the standard output (the shell window) the content of the completion file. To save to an actual file use the `>` redirect symbol. + +To generate the completion file you can use `arduino-cli completion [bash|zsh|fish] [--no-descriptions]`. By default +this command will print on the standard output (the shell window) the content of the completion file. To save to an +actual file use the `>` redirect symbol. ### Bash -Use `arduino-cli completion bash > arduino-cli.sh` to generate the completion file. -At this point you can move that file in `/etc/bash_completion.d/` (root access is required) with `sudo mv arduino-cli.sh /etc/bash_completion.d/`. + +Use `arduino-cli completion bash > arduino-cli.sh` to generate the completion file. At this point you can move that file +in `/etc/bash_completion.d/` (root access is required) with `sudo mv arduino-cli.sh /etc/bash_completion.d/`. A not recommended alternative is to source the completion file in `~/.bashrc`. Remember to open a new shell to test the functionality. ### Zsh -Use `arduino-cli completion zsh > _arduino-cli` to generate the completion file. -At this point you can place the file in a directory listed in your `fpath` if you have already created a directory to store your completion. + +Use `arduino-cli completion zsh > _arduino-cli` to generate the completion file. At this point you can place the file in +a directory listed in your `fpath` if you have already created a directory to store your completion. Or if you want you can create a directory, add it to your `fpath` and copy the file in it: @@ -29,17 +35,24 @@ Or if you want you can create a directory, add it to your `fpath` and copy the f Remember to open a new shell to test the functionality. ### Fish -Use `arduino-cli completion fish > arduino-cli.fish` to generate the completion file. -At this point you can place the file in `~/.config/fish/completions` as stated in the [official documentation](http://fishshell.com/docs/current/index.html#where-to-put-completions). -Remember to create the directory if it's not already there `mkdir -p ~/.config/fish/completions/` and then place the completion file in there with `mv arduino-cli.fish ~/.config/fish/completions/` + +Use `arduino-cli completion fish > arduino-cli.fish` to generate the completion file. At this point you can place the +file in `~/.config/fish/completions` as stated in the +[official documentation](http://fishshell.com/docs/current/index.html#where-to-put-completions). Remember to create the +directory if it's not already there `mkdir -p ~/.config/fish/completions/` and then place the completion file in there +with `mv arduino-cli.fish ~/.config/fish/completions/` Remember to open a new shell to test the functionality. #### Disabling command and flag descriptions -By default fish completion has command and flag description enabled by default. If you want to disable this behaviour you can simply pass the `--no-descriptions` flag when calling `completion` command and the generated file will not have descriptions -*N.B.* -This flag is not compatible with bash or zsh +By default fish completion has command and flag description enabled by default. If you want to disable this behaviour +you can simply pass the `--no-descriptions` flag when calling `completion` command and the generated file will not have +descriptions + +_N.B._ This flag is not compatible with bash or zsh ### Brew -If you install the `arduino-cli` using [homebrew](https://brew.sh/) package manager the completion should work out of the box if you have followed the [official documentation](https://docs.brew.sh/Shell-Completion). + +If you install the `arduino-cli` using [homebrew](https://brew.sh/) package manager the completion should work out of +the box if you have followed the [official documentation](https://docs.brew.sh/Shell-Completion). diff --git a/docs/configuration.md b/docs/configuration.md index 020395ff433..aea470b5677 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,29 +1,22 @@ ## Configuration keys -* `board_manager` - * `additional_urls` - the URLs to any additional Board Manager package index - files needed for your boards platforms. -* `daemon` - options related to running Arduino CLI as a [gRPC] server. - * `port` - TCP port used for gRPC client connections. -* `directories` - directories used by Arduino CLI. - * `data` - directory used to store Board/Library Manager index files and - Board Manager platform installations. - * `downloads` - directory used to stage downloaded archives during - Board/Library Manager installations. - * `user` - the equivalent of the Arduino IDE's - ["sketchbook" directory][sketchbook directory]. Library Manager - installations are made to the `libraries` subdirectory of the user - directory. -* `logging` - configuration options for Arduino CLI's logs. - * `file` - path to the file where logs will be written. - * `format` - output format for the logs. Allowed values are `text` or - `json`. - * `level` - messages with this level and above will be logged. Valid levels - are: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`. -* `telemetry` - settings related to the collection of data used for continued -improvement of Arduino CLI. - * `addr` - TCP port used for telemetry communication. - * `enabled` - controls the use of telemetry. +- `board_manager` + - `additional_urls` - the URLs to any additional Board Manager package index files needed for your boards platforms. +- `daemon` - options related to running Arduino CLI as a [gRPC] server. + - `port` - TCP port used for gRPC client connections. +- `directories` - directories used by Arduino CLI. + - `data` - directory used to store Board/Library Manager index files and Board Manager platform installations. + - `downloads` - directory used to stage downloaded archives during Board/Library Manager installations. + - `user` - the equivalent of the Arduino IDE's ["sketchbook" directory][sketchbook directory]. Library Manager + installations are made to the `libraries` subdirectory of the user directory. +- `logging` - configuration options for Arduino CLI's logs. + - `file` - path to the file where logs will be written. + - `format` - output format for the logs. Allowed values are `text` or `json`. + - `level` - messages with this level and above will be logged. Valid levels are: `trace`, `debug`, `info`, `warn`, + `error`, `fatal`, `panic`. +- `telemetry` - settings related to the collection of data used for continued improvement of Arduino CLI. + - `addr` - TCP port used for telemetry communication. + - `enabled` - controls the use of telemetry. ## Configuration methods @@ -33,23 +26,20 @@ Arduino CLI may be configured in three ways: 1. Environment variables 1. Configuration file -If a configuration option is configured by multiple methods, the value set by -the method highest on the above list overwrites the ones below it. +If a configuration option is configured by multiple methods, the value set by the method highest on the above list +overwrites the ones below it. If a configuration option is not set, Arduino CLI uses a default value. -[`arduino-cli config dump`][arduino-cli config dump] displays the current -configuration values. +[`arduino-cli config dump`][arduino-cli config dump] displays the current configuration values. ### Command line flags -Arduino CLI's command line flags are documented in the command line help and the -[Arduino CLI command reference]. +Arduino CLI's command line flags are documented in the command line help and the [Arduino CLI command reference]. #### Example -Setting an additional Board Manager URL using the -[`--additional-urls`][arduino-cli global flags] command line flag: +Setting an additional Board Manager URL using the [`--additional-urls`][arduino-cli global flags] command line flag: ```shell $ arduino-cli core update-index --additional-urls https://downloads.arduino.cc/packages/package_staging_index.json @@ -57,19 +47,16 @@ $ arduino-cli core update-index --additional-urls https://downloads.arduino.cc/p ### Environment variables -All configuration options can be set via environment variables. The variable -names start with `ARDUINO`, followed by the configuration key names, with each -component separated by `_`. For example, the `ARDUINO_DIRECTORIES_USER` -environment variable sets the `directories.user` configuration option. +All configuration options can be set via environment variables. The variable names start with `ARDUINO`, followed by the +configuration key names, with each component separated by `_`. For example, the `ARDUINO_DIRECTORIES_USER` environment +variable sets the `directories.user` configuration option. -On Linux or macOS, you can use the [`export` command][export command] to set -environment variables. On Windows cmd, you can use the -[`set` command][set command]. +On Linux or macOS, you can use the [`export` command][export command] to set environment variables. On Windows cmd, you +can use the [`set` command][set command]. #### Example -Setting an additional Board Manager URL using the -`ARDUINO_BOARD_MANAGER_ADDITIONAL_URLS` environment variable: +Setting an additional Board Manager URL using the `ARDUINO_BOARD_MANAGER_ADDITIONAL_URLS` environment variable: ```sh $ export ARDUINO_BOARD_MANAGER_ADDITIONAL_URLS=https://downloads.arduino.cc/packages/package_staging_index.json @@ -77,11 +64,10 @@ $ export ARDUINO_BOARD_MANAGER_ADDITIONAL_URLS=https://downloads.arduino.cc/pack ### Configuration file -[`arduino-cli config init`][arduino-cli config init] creates or updates a -configuration file with the current configuration settings. +[`arduino-cli config init`][arduino-cli config init] creates or updates a configuration file with the current +configuration settings. -This allows saving the options set by command line flags or environment -variables. For example: +This allows saving the options set by command line flags or environment variables. For example: ```sh arduino-cli config init --additional-urls https://downloads.arduino.cc/packages/package_staging_index.json @@ -89,38 +75,33 @@ arduino-cli config init --additional-urls https://downloads.arduino.cc/packages/ #### File name -The configuration file must be named `arduino-cli`, with the appropriate file -extension for the file's format. +The configuration file must be named `arduino-cli`, with the appropriate file extension for the file's format. #### Supported formats -`arduino-cli config init` creates a YAML file, however a variety of common -formats are supported: +`arduino-cli config init` creates a YAML file, however a variety of common formats are supported: -* [JSON] -* [TOML] -* [YAML] -* [Java properties file] -* [HCL] -* envfile -* [INI] +- [JSON] +- [TOML] +- [YAML] +- [Java properties file] +- [HCL] +- envfile +- [INI] #### Locations Configuration files in the following locations are recognized by Arduino CLI: -1. Location specified by the [`--config-file`][Arduino CLI command reference] -command line flag +1. Location specified by the [`--config-file`][arduino cli command reference] command line flag 1. Current working directory -1. Any parent directory of the current working directory (more immediate parents -having higher precedence) +1. Any parent directory of the current working directory (more immediate parents having higher precedence) 1. Arduino CLI data directory (as configured by `directories.data`) -If multiple configuration files are present, the one highest on the above list -is used. Configuration files are not combined. +If multiple configuration files are present, the one highest on the above list is used. Configuration files are not +combined. -The location of the active configuration file can be determined by running the -command: +The location of the active configuration file can be determined by running the command: ```sh arduino-cli config dump --verbose @@ -133,7 +114,7 @@ Setting an additional Board Manager URL using a YAML format configuration file: ```yaml board_manager: additional_urls: - - https://downloads.arduino.cc/packages/package_staging_index.json + - https://downloads.arduino.cc/packages/package_staging_index.json ``` Doing the same using a TOML format file: @@ -143,18 +124,17 @@ Doing the same using a TOML format file: additional_urls = [ "https://downloads.arduino.cc/packages/package_staging_index.json" ] ``` - -[gRPC]: https://grpc.io +[grpc]: https://grpc.io [sketchbook directory]: sketch-specification.md#sketchbook [arduino-cli config dump]: ../commands/arduino-cli_config_dump -[Arduino CLI command reference]: ../commands/arduino-cli +[arduino cli command reference]: ../commands/arduino-cli [arduino-cli global flags]: ../commands/arduino-cli_config/#options-inherited-from-parent-commands [export command]: https://ss64.com/bash/export.html [set command]: https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1 [arduino-cli config init]: ../commands/arduino-cli_config_init -[JSON]: https://www.json.org -[TOML]: https://github.com/toml-lang/toml -[YAML]: https://en.wikipedia.org/wiki/YAML -[Java properties file]: https://en.wikipedia.org/wiki/.properties -[HCL]: https://github.com/hashicorp/hcl -[INI]: https://en.wikipedia.org/wiki/INI_file +[json]: https://www.json.org +[toml]: https://github.com/toml-lang/toml +[yaml]: https://en.wikipedia.org/wiki/YAML +[java properties file]: https://en.wikipedia.org/wiki/.properties +[hcl]: https://github.com/hashicorp/hcl +[ini]: https://en.wikipedia.org/wiki/INI_file diff --git a/docs/getting-started.md b/docs/getting-started.md index 7264b422453..a558fdaeb06 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,10 +1,10 @@ -Despite the lack of feature parity at the moment, Arduino CLI provides many of -the features you can find in the Arduino IDE. Let's see some examples. +Despite the lack of feature parity at the moment, Arduino CLI provides many of the features you can find in the Arduino +IDE. Let's see some examples. ## Before you start -`arduino-cli` is a container of commands and each command has its own -dedicated help text that can be shown with the `help` command like this: +`arduino-cli` is a container of commands and each command has its own dedicated help text that can be shown with the +`help` command like this: ```console $ arduino-cli help core @@ -42,9 +42,8 @@ Use "arduino-cli core [command] --help" for more information about a command. ## Create a configuration file -Arduino CLI doesn't strictly require a configuration file to work because the -command line interface provides any possible functionality. However, having one -can spare you a lot of typing when issuing a command, so let's go ahead and +Arduino CLI doesn't strictly require a configuration file to work because the command line interface provides any +possible functionality. However, having one can spare you a lot of typing when issuing a command, so let's go ahead and create it with: ```sh @@ -52,23 +51,20 @@ $ arduino-cli config init Config file written: /home/luca/.arduino15/arduino-cli.yaml ``` -If you inspect the contents of `arduino-cli.yaml`, you'll find the available -options with their respective default values. For more information, see the -[configuration documentation]. +If you inspect the contents of `arduino-cli.yaml`, you'll find the available options with their respective default +values. For more information, see the [configuration documentation]. ## Create a new sketch -To create a new sketch named `MyFirstSketch` in the current directory, run -the following command: +To create a new sketch named `MyFirstSketch` in the current directory, run the following command: ```sh $ arduino-cli sketch new MyFirstSketch Sketch created in: /home/luca/MyFirstSketch ``` -A sketch is a folder containing assets like source files and libraries; the -`new` command creates for you a .ino file called `MyFirstSketch.ino` -containing Arduino boilerplate code: +A sketch is a folder containing assets like source files and libraries; the `new` command creates for you a .ino file +called `MyFirstSketch.ino` containing Arduino boilerplate code: ```sh $ cat $HOME/MyFirstSketch/MyFirstSketch.ino @@ -79,8 +75,8 @@ void loop() { } ``` -At this point you can use your favourite file editor or IDE to open the -file `$HOME/MyFirstSketch/MyFirstSketch.ino` and change the code like this: +At this point you can use your favourite file editor or IDE to open the file `$HOME/MyFirstSketch/MyFirstSketch.ino` and +change the code like this: ```c void setup() { @@ -97,16 +93,15 @@ void loop() { ## Connect the board to your PC -The first thing to do upon a fresh install is to update the local cache of -available platforms and libraries by running: +The first thing to do upon a fresh install is to update the local cache of available platforms and libraries by running: ```sh $ arduino-cli core update-index Updating index: package_index.json downloaded ``` -After connecting the board to your PC by using the USB cable, you should be -able to check whether it's been recognized by running: +After connecting the board to your PC by using the USB cable, you should be able to check whether it's been recognized +by running: ```sh $ arduino-cli board list @@ -114,14 +109,12 @@ Port Type Board Name FQBN Core /dev/ttyACM1 Serial Port (USB) Arduino/Genuino MKR1000 arduino:samd:mkr1000 arduino:samd ``` -In this example, the MKR1000 board was recognized and from the output of the -command you see the platform core called `arduino:samd` is the one that needs -to be installed to make it work. +In this example, the MKR1000 board was recognized and from the output of the command you see the platform core called +`arduino:samd` is the one that needs to be installed to make it work. -If you see an `Unknown` board listed, uploading -should still work as long as you identify the platform core and use the correct -FQBN string. When a board is not detected for whatever reason, you can list all -the supported boards and their FQBN strings by running the following: +If you see an `Unknown` board listed, uploading should still work as long as you identify the platform core and use the +correct FQBN string. When a board is not detected for whatever reason, you can list all the supported boards and their +FQBN strings by running the following: ```sh $ arduino-cli board listall mkr @@ -136,7 +129,7 @@ Arduino/Genuino MKR1000 arduino:samd:mkr1000 ## Install the core for your board -To install the ``arduino:samd`` platform core, run the following: +To install the `arduino:samd` platform core, run the following: ```sh $ arduino-cli core install arduino:samd @@ -173,20 +166,18 @@ Great! Now we are ready to compile and upload the sketch. ## Adding 3rd party cores -If your board requires 3rd party core packages to work, you can list the URLs -to additional package indexes in the Arduino CLI configuration file. +If your board requires 3rd party core packages to work, you can list the URLs to additional package indexes in the +Arduino CLI configuration file. -For example, to add the ESP8266 core, edit the configuration file and change the -`board_manager` settings as follows: +For example, to add the ESP8266 core, edit the configuration file and change the `board_manager` settings as follows: ```yaml board_manager: - additional_urls: + additional_urls: - https://arduino.esp8266.com/stable/package_esp8266com_index.json ``` -From now on, commands supporting custom cores will automatically use the -additional URL from the configuration file: +From now on, commands supporting custom cores will automatically use the additional URL from the configuration file: ```sh $ arduino-cli core update-index @@ -199,9 +190,8 @@ ID Version Name esp8266:esp8266 2.5.2 esp8266 ``` -Alternatively, you can pass a link to the additional package index file with the -`--additional-urls` option, that has to be specified every time and for every -command that operates on a 3rd party platform core, for example: +Alternatively, you can pass a link to the additional package index file with the `--additional-urls` option, that has to +be specified every time and for every command that operates on a 3rd party platform core, for example: ```sh $ arduino-cli core update-index --additional-urls https://arduino.esp8266.com/stable/package_esp8266com_index.json @@ -214,16 +204,14 @@ esp8266:esp8266 2.5.2 esp8266 ## Compile and upload the sketch -To compile the sketch you run the `compile` command, passing the proper FQBN -string: +To compile the sketch you run the `compile` command, passing the proper FQBN string: ```sh $ arduino-cli compile --fqbn arduino:samd:mkr1000 MyFirstSketch Sketch uses 9600 bytes (3%) of program storage space. Maximum is 262144 bytes. ``` -To upload the sketch to your board, run the following command, using the serial -port your board is connected to: +To upload the sketch to your board, run the following command, using the serial port your board is connected to: ```sh $ arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:samd:mkr1000 MyFirstSketch @@ -261,9 +249,8 @@ CPU reset. ## Add libraries -If you need to add more functionalities to your sketch, chances are some of the -libraries available in the Arduino ecosystem already provide what you need. -For example, if you need a debouncing strategy to better handle button inputs, +If you need to add more functionalities to your sketch, chances are some of the libraries available in the Arduino +ecosystem already provide what you need. For example, if you need a debouncing strategy to better handle button inputs, you can try searching for the `debouncer` keyword: ```sh @@ -300,7 +287,7 @@ Name: "SoftTimer" Versions: [3.0.0, 3.1.0, 3.1.1, 3.1.2, 3.1.3, 3.1.5, 3.2.0] ``` -Our favourite is ``FTDebouncer``, let's install it by running: +Our favourite is `FTDebouncer`, let's install it by running: ```sh $ arduino-cli lib install FTDebouncer @@ -311,21 +298,16 @@ Installing FTDebouncer@1.3.0... Installed FTDebouncer@1.3.0 ``` - -Using the ``daemon`` mode and the gRPC interface ------------------------------------------------- +## Using the `daemon` mode and the gRPC interface Arduino CLI can be launched as a gRPC server via the `daemon` command. -The [client_example] folder contains a sample client code that shows how to -interact with the gRPC server. Available services and messages are detailed -in the [gRPC reference] pages. - +The [client_example] folder contains a sample client code that shows how to interact with the gRPC server. Available +services and messages are detailed in the [gRPC reference] pages. -To provide observability for the gRPC server activities besides logs, -the `daemon` mode activates and exposes by default a [Prometheus](https://prometheus.io/) -endpoint (http://localhost:9090/metrics) that can be fetched for -telemetry data like: +To provide observability for the gRPC server activities besides logs, the `daemon` mode activates and exposes by default +a [Prometheus](https://prometheus.io/) endpoint (http://localhost:9090/metrics) that can be fetched for telemetry data +like: ```text # TYPE daemon_compile counter @@ -335,8 +317,7 @@ daemon_compile{buildProperties="",exportFile="",fqbn="arduino:samd:mkr1000",inst daemon_board_list{installationID="ed6f1f22-1fbe-4b1f-84be-84d035b6369c",success="true"} 1 1580385724833 ``` -The telemetry settings are exposed via the ``telemetry`` section -in the CLI configuration: +The telemetry settings are exposed via the `telemetry` section in the CLI configuration: ```yaml telemetry: @@ -346,5 +327,5 @@ telemetry: [configuration documentation]: configuration.md [client_example]: https://github.com/arduino/arduino-cli/blob/master/client_example -[gRPC reference]: ../rpc/commands -[Prometheus]: https://prometheus.io/ +[grpc reference]: ../rpc/commands +[prometheus]: https://prometheus.io/ diff --git a/docs/index.md b/docs/index.md index 6e6ceb58d78..d40820b0114 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,25 +1,20 @@ -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. ## Installation -You have several options to install the latest version of the Arduino -CLI on your system, see the [installation] page. +You have several options to install the latest version of the Arduino CLI on your system, see the [installation] page. ## Getting started -Follow the [Getting started guide] to see how to use the most -common CLI commands available. +Follow the [Getting started guide] to see how to use the most common CLI commands available. ## Using the gRPC interface -The [client_example] folder contains a sample program that shows how to use gRPC -interface of the CLI. Available services and messages are detailed in the -[gRPC reference] pages. - +The [client_example] folder contains a sample program that shows how to use gRPC interface of the CLI. Available +services and messages are detailed in the [gRPC reference] pages. [installation]: installation.md -[Getting started guide]: getting-started.md +[getting started guide]: getting-started.md [client_example]: https://github.com/arduino/arduino-cli/blob/master/client_example -[gRPC reference]: rpc/commands \ No newline at end of file +[grpc reference]: rpc/commands diff --git a/docs/installation.md b/docs/installation.md index c235f063ae5..b1ffb9febce 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,20 +1,20 @@ ### Install via Homebrew (macOS/Linux) -The Arduino CLI is available as a Homebrew formula since version -`0.5.0`: +The Arduino CLI is available as a Homebrew formula since version `0.5.0`: ```sh brew update brew install arduino-cli ``` + #### Command line completion + [Command line completion](command-line-completion.md#brew) files are already bundled in the homebrew installation. ### Use the install script -The script requires `sh`. This is always available on Linux and macOS. `sh` is -not available by default on Windows. The script may be run on Windows by -installing [Git for Windows], then running it from Git Bash. +The script requires `sh`. This is always available on Linux and macOS. `sh` is not available by default on Windows. The +script may be run on Windows by installing [Git for Windows], then running it from Git Bash. This script will install the latest version of Arduino CLI to `$PWD/bin`: @@ -22,19 +22,17 @@ This script will install the latest version of Arduino CLI to `$PWD/bin`: curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh ``` -If you want to target a different directory, for example `~/local/bin`, set the -`BINDIR` environment variable like this: +If you want to target a different directory, for example `~/local/bin`, set the `BINDIR` environment variable like this: ```sh curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | BINDIR=~/local/bin sh ``` -If you would like to use the `arduino-cli` command from any location, install -Arduino CLI to a directory already in your `PATH` or add the Arduino CLI -installation path to your `PATH` environment variable. +If you would like to use the `arduino-cli` command from any location, install Arduino CLI to a directory already in your +`PATH` or add the Arduino CLI installation path to your `PATH` environment variable. -If you want to download a specific arduino-cli version, for example `0.9.0`, pass the -version number as a parameter like this: +If you want to download a specific arduino-cli version, for example `0.9.0`, pass the version number as a parameter like +this: ```sh curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh -s 0.9.0 @@ -42,34 +40,31 @@ curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install. ### Download -Pre-built binaries for all the supported platforms are available for download -from the links below. +Pre-built binaries for all the supported platforms are available for download from the links below. -If you would like to use the `arduino-cli` command from any location, extract -the downloaded file to a directory already in your `PATH` or add the Arduino CLI -installation path to your `PATH` environment variable. +If you would like to use the `arduino-cli` command from any location, extract the downloaded file to a directory already +in your `PATH` or add the Arduino CLI installation path to your `PATH` environment variable. #### Latest packages -Platform | | | ---------- | ------------------ | ------------------ | -Linux | [Linux 32 bit] | [Linux 64 bit] | -Linux ARM | [Linux ARM 32 bit] | [Linux ARM 64 bit] | -Windows | [Windows 32 bit] | [Windows 64 bit] | -Mac OSX | | [Mac OSX] | - -[Linux 64 bit]: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Linux_64bit.tar.gz -[Linux 32 bit]: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Linux_32bit.tar.gz -[Linux ARM 64 bit]: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Linux_ARM64.tar.gz -[Linux ARM 32 bit]: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Linux_ARMv7.tar.gz -[Windows 64 bit]: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Windows_64bit.zip -[Windows 32 bit]: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Windows_32bit.zip -[Mac OSX]: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_macOS_64bit.tar.gz +| Platform | | | +| --------- | ------------------ | ------------------ | +| Linux | [Linux 32 bit] | [Linux 64 bit] | +| Linux ARM | [Linux ARM 32 bit] | [Linux ARM 64 bit] | +| Windows | [Windows 32 bit] | [Windows 64 bit] | +| Mac OSX | | [Mac OSX] | + +[linux 64 bit]: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Linux_64bit.tar.gz +[linux 32 bit]: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Linux_32bit.tar.gz +[linux arm 64 bit]: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Linux_ARM64.tar.gz +[linux arm 32 bit]: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Linux_ARMv7.tar.gz +[windows 64 bit]: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Windows_64bit.zip +[windows 32 bit]: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Windows_32bit.zip +[mac osx]: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_macOS_64bit.tar.gz > **Deprecation notice**: links in the form - `http://downloads.arduino.cc/arduino-cli/arduino-cli-latest-.tar.bz2` - won’t be further updated. That URL will provide the version - `0.3.7-alpha.preview`, regardless of further releases. +> `http://downloads.arduino.cc/arduino-cli/arduino-cli-latest-.tar.bz2` won’t be further updated. That URL +> will provide the version `0.3.7-alpha.preview`, regardless of further releases. #### Previous versions @@ -77,49 +72,45 @@ These are available from the [releases page](https://github.com/arduino/arduino- #### Nightly builds -These builds are generated every day at 01:00 GMT from the `master` branch and -should be considered unstable. In order to get the latest nightly build -available for the supported platform, use the following links: - -Platform | | | ---------- | -------------------------- | -------------------------- | -Linux | [Nightly Linux 32 bit] | [Nightly Linux 64 bit] | -Linux ARM | [Nightly Linux ARM 32 bit] | [Nightly Linux ARM 64 bit] | -Windows | [Nightly Windows 32 bit] | [Nightly Windows 64 bit] | -Mac OSX | | [Nightly Mac OSX] | - -[Nightly Linux 64 bit]: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Linux_64bit.tar.gz -[Nightly Linux 32 bit]: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Linux_32bit.tar.gz -[Nightly Linux ARM 64 bit]: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Linux_ARM64.tar.gz -[Nightly Linux ARM 32 bit]: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Linux_ARMv7.tar.gz -[Nightly Windows 64 bit]: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Windows_64bit.zip -[Nightly Windows 32 bit]: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Windows_32bit.zip -[Nightly Mac OSX]: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_macOS_64bit.tar.gz - -> These links return a `302: Found` response, redirecting to latest - generated builds by replacing `latest` with the latest available build - date, using the format YYYYMMDD (i.e for 2019/Aug/06 `latest` is - replaced with `20190806` ) +These builds are generated every day at 01:00 GMT from the `master` branch and should be considered unstable. In order +to get the latest nightly build available for the supported platform, use the following links: + +| Platform | | | +| --------- | -------------------------- | -------------------------- | +| Linux | [Nightly Linux 32 bit] | [Nightly Linux 64 bit] | +| Linux ARM | [Nightly Linux ARM 32 bit] | [Nightly Linux ARM 64 bit] | +| Windows | [Nightly Windows 32 bit] | [Nightly Windows 64 bit] | +| Mac OSX | | [Nightly Mac OSX] | + +[nightly linux 64 bit]: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Linux_64bit.tar.gz +[nightly linux 32 bit]: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Linux_32bit.tar.gz +[nightly linux arm 64 bit]: + https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Linux_ARM64.tar.gz +[nightly linux arm 32 bit]: + https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Linux_ARMv7.tar.gz +[nightly windows 64 bit]: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Windows_64bit.zip +[nightly windows 32 bit]: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Windows_32bit.zip +[nightly mac osx]: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_macOS_64bit.tar.gz + +> These links return a `302: Found` response, redirecting to latest generated builds by replacing `latest` with the +> latest available build date, using the format YYYYMMDD (i.e for 2019/Aug/06 `latest` is replaced with `20190806` ) Checksums for the nightly builds are available at `https://downloads.arduino.cc/arduino-cli/nightly/nightly--checksums.txt` ### Build from source -If you’re familiar with Golang or if you want to contribute to the -project, you will probably build the `arduino-cli` locally with your -Go toolchain. Please refer to the [CONTRIBUTING] document for setup instructions. +If you’re familiar with Golang or if you want to contribute to the project, you will probably build the `arduino-cli` +locally with your Go toolchain. Please refer to the [CONTRIBUTING] document for setup instructions. -If you don’t have a working Golang environment or if you want to build -`arduino-cli` targeting different platforms, you can use Docker to get -a binary directly from sources. From the project folder run: +If you don’t have a working Golang environment or if you want to build `arduino-cli` targeting different platforms, you +can use Docker to get a binary directly from sources. From the project folder run: ```sh docker run -v $PWD:/arduino-cli -w /arduino-cli -e PACKAGE_NAME_PREFIX='snapshot' arduino/arduino-cli:builder-1 goreleaser --rm-dist --snapshot --skip-publish ``` -Once the build is over, you will find a `./dist/` folder containing the packages -built out of the current source tree. +Once the build is over, you will find a `./dist/` folder containing the packages built out of the current source tree. -[Git for Windows]: https://gitforwindows.org/ -[CONTRIBUTING]: CONTRIBUTING.md +[git for windows]: https://gitforwindows.org/ +[contributing]: CONTRIBUTING.md diff --git a/docs/integration-options.md b/docs/integration-options.md index 4736d14820c..2675b59e38b 100644 --- a/docs/integration-options.md +++ b/docs/integration-options.md @@ -1,137 +1,112 @@ # The three pillars of the Arduino CLI -The Arduino CLI is an open source Command Line Application written in [Golang] -that can be used from a terminal to compile, verify and upload sketches to -Arduino boards and that’s capable of managing all the software and tools needed -in the process. But don’t get fooled by its name: Arduino CLI can do much more -than the average console application, as shown by the [Arduino Pro IDE] and -[Arduino Create], which rely on it for similar purposes but each one in a -completely different way from the other. In this article we introduce the three -pillars of the Arduino CLI, explaining how we designed the software so that it -can be effectively leveraged under different scenarios. +The Arduino CLI is an open source Command Line Application written in [Golang] that can be used from a terminal to +compile, verify and upload sketches to Arduino boards and that’s capable of managing all the software and tools needed +in the process. But don’t get fooled by its name: Arduino CLI can do much more than the average console application, as +shown by the [Arduino Pro IDE] and [Arduino Create], which rely on it for similar purposes but each one in a completely +different way from the other. In this article we introduce the three pillars of the Arduino CLI, explaining how we +designed the software so that it can be effectively leveraged under different scenarios. ## The first pillar: command line interface ### Console applications for humans -As you might expect, the first way to use the Arduino CLI is from a terminal and -by a human, and user experience plays a key role here. The UX is under a -continuous improvement process as we want the tool to be powerful without being -too complicated. We heavily rely on sub-commands to provide a rich set of -different operations logically grouped together, so that users can easily -explore the interface while getting very specific contextual help. +As you might expect, the first way to use the Arduino CLI is from a terminal and by a human, and user experience plays a +key role here. The UX is under a continuous improvement process as we want the tool to be powerful without being too +complicated. We heavily rely on sub-commands to provide a rich set of different operations logically grouped together, +so that users can easily explore the interface while getting very specific contextual help. ![contextual help screenshot][] ### Console applications for robots -Humans are not the only type of customers we want to support and the Arduino CLI -was also designed to be used programmatically - think about automation pipelines -or a [CI][continuous integration]/[CD][continuous deployment] system. -There are some niceties to observe when you write software that’s supposed to be -easy to run when unattended and one in particular is the ability to run without -a configuration file. This is possible because every configuration option you -find in the arduino-cli.yaml configuration file can be provided either through a -command line flag or by setting an environment variable. To give an example, the -following commands are all equivalent and will proceed fetching the unstable -package index that can be used to work with experimental versions of cores: +Humans are not the only type of customers we want to support and the Arduino CLI was also designed to be used +programmatically - think about automation pipelines or a [CI][continuous integration]/[CD][continuous deployment] +system. There are some niceties to observe when you write software that’s supposed to be easy to run when unattended and +one in particular is the ability to run without a configuration file. This is possible because every configuration +option you find in the arduino-cli.yaml configuration file can be provided either through a command line flag or by +setting an environment variable. To give an example, the following commands are all equivalent and will proceed fetching +the unstable package index that can be used to work with experimental versions of cores: ![configuration methods screenshot][] See the [configuration documentation] for details about Arduino CLI's configuration system. -Consistent with the previous paragraph, when it comes to providing output the -Arduino CLI aims to be user friendly but also slightly verbose, something that -doesn’t play well with robots. This is why we added an option to provide output -that’s easy to parse, for example the following figure shows what getting the -software version in [JSON] format looks like. +Consistent with the previous paragraph, when it comes to providing output the Arduino CLI aims to be user friendly but +also slightly verbose, something that doesn’t play well with robots. This is why we added an option to provide output +that’s easy to parse, for example the following figure shows what getting the software version in [JSON] format looks +like. ![JSON output screenshot][] -Even if not related to software design, one last feature that’s worth mentioning -is the availability of a one-line [installation script] that can be used to make -the latest version of the Arduino CLI available on most systems with an HTTP -client like curl or wget and a shell like bash. +Even if not related to software design, one last feature that’s worth mentioning is the availability of a one-line +[installation script] that can be used to make the latest version of the Arduino CLI available on most systems with an +HTTP client like curl or wget and a shell like bash. -For more information on Arduino CLI's command line interface, see the -[command reference]. +For more information on Arduino CLI's command line interface, see the [command reference]. ## The second pillar: gRPC interface -[gRPC] is a high performance [RPC] framework that can efficiently connect client -and server applications. The Arduino CLI can act as a gRPC server (we call it -[daemon mode]), exposing a set of procedures that implement the very same set of -features of the command line interface and waiting for clients to connect and -use them. To give an idea, the following is some [Golang] code capable of -retrieving the version number of a remote running Arduino CLI server instance: +[gRPC] is a high performance [RPC] framework that can efficiently connect client and server applications. The Arduino +CLI can act as a gRPC server (we call it [daemon mode]), exposing a set of procedures that implement the very same set +of features of the command line interface and waiting for clients to connect and use them. To give an idea, the +following is some [Golang] code capable of retrieving the version number of a remote running Arduino CLI server +instance: ![gRPC interface screenshot][] -gRPC is language agnostic: even if the example is written in Golang, the -programming language used for the client can be Python, JavaScript or any of the -many [supported ones][gRPC supported languages], leading to a variety of -possible scenarios. The new [Arduino Pro IDE] is a good example of how to -leverage the daemon mode of the Arduino CLI with a clean separation of concerns: -the Pro IDE knows nothing about how to download a core, compile a sketch or talk -to an Arduino board and it demands all these features of an Arduino CLI instance. -Conversely, the Arduino CLI doesn’t even know that the client that’s connected -is the Pro IDE, and neither does it care. +gRPC is language agnostic: even if the example is written in Golang, the programming language used for the client can be +Python, JavaScript or any of the many [supported ones][grpc supported languages], leading to a variety of possible +scenarios. The new [Arduino Pro IDE] is a good example of how to leverage the daemon mode of the Arduino CLI with a +clean separation of concerns: the Pro IDE knows nothing about how to download a core, compile a sketch or talk to an +Arduino board and it demands all these features of an Arduino CLI instance. Conversely, the Arduino CLI doesn’t even +know that the client that’s connected is the Pro IDE, and neither does it care. -For more information on Arduino CLI's gRPC interface, see the -[gRPC interface reference]. +For more information on Arduino CLI's gRPC interface, see the [gRPC interface reference]. ## The third pillar: embedding -Arduino CLI is written in [Golang] and the code is organized in a way that makes -it easy to use it as a library by including the modules you need in another -Golang application at compile time. Both the first and second pillars rely on a -common Golang API, a set of functions that abstract all the functionalities -offered by the Arduino CLI, so that when we provide a fix or a new feature, they -are automatically available to both the command line and gRPC interfaces. -The source modules implementing this API can be imported in other Golang -programs to embed a full fledged Arduino CLI. For example, this is how some -backend services powering [Arduino Create] can compile sketches and manage -libraries. Just to give you a taste of what it means to embed the Arduino CLI, -here is how to search for a core using the API: +Arduino CLI is written in [Golang] and the code is organized in a way that makes it easy to use it as a library by +including the modules you need in another Golang application at compile time. Both the first and second pillars rely on +a common Golang API, a set of functions that abstract all the functionalities offered by the Arduino CLI, so that when +we provide a fix or a new feature, they are automatically available to both the command line and gRPC interfaces. The +source modules implementing this API can be imported in other Golang programs to embed a full fledged Arduino CLI. For +example, this is how some backend services powering [Arduino Create] can compile sketches and manage libraries. Just to +give you a taste of what it means to embed the Arduino CLI, here is how to search for a core using the API: ![Go library interface screenshot][] -Embedding the Arduino CLI is limited to Golang applications and requires a deep -knowledge of its internals; for the average use case the gRPC interface might be -a better alternative, nevertheless this remains a valid option that we use and -provide support for. +Embedding the Arduino CLI is limited to Golang applications and requires a deep knowledge of its internals; for the +average use case the gRPC interface might be a better alternative, nevertheless this remains a valid option that we use +and provide support for. ## Conclusions -You can start playing with the Arduino CLI right away. The code is open source -and [the repo][Arduino CLI repository] contains -[example code showing how to implement a gRPC client][gRPC client example]. If -you’re curious about how we designed the low level API, have a look at the -[commands package] and don’t hesitate to leave feedback on the [issue tracker] -if you’ve got a use case that doesn’t fit one of the three pillars. +You can start playing with the Arduino CLI right away. The code is open source and [the repo][arduino cli repository] +contains [example code showing how to implement a gRPC client][grpc client example]. If you’re curious about how we +designed the low level API, have a look at the [commands package] and don’t hesitate to leave feedback on the [issue +tracker] if you’ve got a use case that doesn’t fit one of the three pillars. - -[Golang]: https://golang.org/ -[Arduino Pro IDE]: https://www.arduino.cc/pro/arduino-pro-ide -[Arduino Create]: https://create.arduino.cc +[golang]: https://golang.org/ +[arduino pro ide]: https://www.arduino.cc/pro/arduino-pro-ide +[arduino create]: https://create.arduino.cc [continuous integration]: https://en.wikipedia.org/wiki/Continuous_integration [continuous deployment]: https://en.wikipedia.org/wiki/Continuous_deployment [configuration documentation]: configuration.md -[JSON]: https://www.json.org +[json]: https://www.json.org [installation script]: installation.md#use-the-install-script [command reference]: ../commands/arduino-cli -[gRPC]: https://grpc.io/ -[RPC]: https://en.wikipedia.org/wiki/Remote_procedure_call +[grpc]: https://grpc.io/ +[rpc]: https://en.wikipedia.org/wiki/Remote_procedure_call [daemon mode]: ../commands/arduino-cli_daemon -[gRPC interface reference]: ../rpc/commands -[gRPC supported languages]: https://grpc.io/docs/languages/ -[Arduino CLI repository]: https://github.com/arduino/arduino-cli -[gRPC client example]: https://github.com/arduino/arduino-cli/blob/master/client_example +[grpc interface reference]: ../rpc/commands +[grpc supported languages]: https://grpc.io/docs/languages/ +[arduino cli repository]: https://github.com/arduino/arduino-cli +[grpc client example]: https://github.com/arduino/arduino-cli/blob/master/client_example [commands package]: https://github.com/arduino/arduino-cli/tree/master/commands [issue tracker]: https://github.com/arduino/arduino-cli/issues - [contextual help screenshot]: img/CLI_contextual_help_screenshot.png [configuration methods screenshot]: img/CLI_configuration_methods_screenshot.png -[JSON output screenshot]: img/CLI_JSON_output_screenshot.png -[gRPC interface screenshot]: img/CLI_gRPC_interface_screenshot.png -[Go library interface screenshot]: img/CLI_Go_library_interface_screenshot.png +[json output screenshot]: img/CLI_JSON_output_screenshot.png +[grpc interface screenshot]: img/CLI_gRPC_interface_screenshot.png +[go library interface screenshot]: img/CLI_Go_library_interface_screenshot.png diff --git a/docs/library-specification.md b/docs/library-specification.md index f48344ea568..3ab86d5d290 100644 --- a/docs/library-specification.md +++ b/docs/library-specification.md @@ -1,57 +1,93 @@ This is the specification for the Arduino library format, to be used with Arduino IDE 1.5.x onwards. -* rev.1 has been implemented starting with Arduino IDE version 1.5.3 (now superseded by rev.2) -* rev.2 will be implemented starting from version Arduino IDE 1.5.6 -* rev.2.1 will be implemented starting from version Arduino IDE 1.6.10 -* rev.2.2 will be implemented starting from version Arduino IDE 1.8.10 +- rev.1 has been implemented starting with Arduino IDE version 1.5.3 (now superseded by rev.2) +- rev.2 will be implemented starting from version Arduino IDE 1.5.6 +- rev.2.1 will be implemented starting from version Arduino IDE 1.6.10 +- rev.2.2 will be implemented starting from version Arduino IDE 1.8.10 -This new library format is intended to be used in tandem with **Library Manager**, available since Arduino IDE 1.6.2. The Library Manager allows users to automatically download and install libraries needed in their projects, with an easy to use graphic interface in the [Arduino IDE](https://www.arduino.cc/en/guide/libraries#toc3)/Pro IDE and [Arduino Web Editor](https://create.arduino.cc/projecthub/Arduino_Genuino/getting-started-with-arduino-web-editor-on-various-platforms-4b3e4a#toc-libraries-and-the-arduino-web-editor-11) as well as [`arduino-cli lib`](../commands/arduino-cli_lib). +This new library format is intended to be used in tandem with **Library Manager**, available since Arduino IDE 1.6.2. +The Library Manager allows users to automatically download and install libraries needed in their projects, with an easy +to use graphic interface in the [Arduino IDE](https://www.arduino.cc/en/guide/libraries#toc3)/Pro IDE and +[Arduino Web Editor](https://create.arduino.cc/projecthub/Arduino_Genuino/getting-started-with-arduino-web-editor-on-various-platforms-4b3e4a#toc-libraries-and-the-arduino-web-editor-11) +as well as [`arduino-cli lib`](../commands/arduino-cli_lib). -More information about how Library Manager works is available [here](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ). +More information about how Library Manager works is available +[here](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ). -Arduino development software supports multiple microcontroller architectures (e.g. AVR, SAM, etc), meaning that libraries may need to work on multiple architectures. The new 1.5 library format doesn’t contain special support for cross-architecture libraries, but it does provide a preprocessor based mechanism for libraries to target sections of code to specific architectures. +Arduino development software supports multiple microcontroller architectures (e.g. AVR, SAM, etc), meaning that +libraries may need to work on multiple architectures. The new 1.5 library format doesn’t contain special support for +cross-architecture libraries, but it does provide a preprocessor based mechanism for libraries to target sections of +code to specific architectures. ## See also -* [Arduino library style guide](http://arduino.cc/en/Reference/APIStyleGuide) -* [Library dependency resolution process documentation](../sketch-build-process/#dependency-resolution) +- [Arduino library style guide](http://arduino.cc/en/Reference/APIStyleGuide) +- [Library dependency resolution process documentation](../sketch-build-process/#dependency-resolution) ## 1.5 library format (rev. 2.2) ### Library metadata -The most significant addition to the format is the ability to add information about the library itself through a properties file called **library.properties**. +The most significant addition to the format is the ability to add information about the library itself through a +properties file called **library.properties**. -This file allows the *Library Manager* to search and install a library and its dependencies in an easy and automated way. It must be located in the root of the library folder. +This file allows the _Library Manager_ to search and install a library and its dependencies in an easy and automated +way. It must be located in the root of the library folder. #### library.properties file format -The library.properties file is a key=value properties list. Every field in this file is UTF-8 encoded. Unless noted otherwise below, **all fields are required**. The available fields are: - -* **name** - the name of the library. Library names must contain only basic letters (`A`-`Z` or `a`-`z`) and numbers (`0`-`9`), spaces (` `), underscores (`_`), dots (`.`) and dashes (`-`). They cannot start with a number. Note that libraries with a `name` value starting with `Arduino` will no longer be allowed [addition to the Library Manager index](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ) as these names are now reserved for official Arduino libraries. -* **version** - version of the library. Version should be [semver](http://semver.org/) compliant. 1.2.0 is correct; 1.2 is accepted; r5, 003, 1.1c are invalid -* **author** - name/nickname of the authors and their email addresses (not mandatory) separated by comma "," -* **maintainer** - name and email of the maintainer -* **sentence** - a sentence explaining the purpose of the library -* **paragraph** - a longer description of the library. The value of **sentence** always will be prepended, so you should start by writing the second sentence here -* **category** - (defaults to `Uncategorized`) if present, one of these: - * Display - * Communication - * Signal Input/Output - * Sensors - * Device Control - * Timing - * Data Storage - * Data Processing - * Other -* **url** - the URL of the library project, for a person to visit. For example, the library's GitHub page. This is used for the "More info" links in Library Manager -* **architectures** - (defaults to `*`) a comma separated list of architectures supported by the library. If the library doesn’t contain architecture specific code use `*` to match all architectures. This field is used as one factor in determining priority when multiple libraries match an `#include` directive and to provide a warning message when the library is compiled for a board of an architecture that doesn't match any on the list. -* **depends** - **(available from Arduino IDE 1.8.10/Arduino CLI 0.7.0)** (optional) a comma-separated list of dependencies (libraries that are needed to build the current library). The Arduino IDE's Library Manager will offer to install the dependencies during installation of the library. [`arduino-cli lib install`](../commands/arduino-cli_lib_install) will automatically install the dependencies. Since spaces are allowed in the `name` of a library, but not commas, you can refer to libraries containing spaces in the name without ambiguity for example:
-`depends=Very long library name, Another library with long-name` -* **dot_a_linkage** - **(available from Arduino IDE 1.6.0 / arduino-builder 1.0.0-beta13)** (optional) when set to `true`, the library will be compiled using a .a (archive) file. First, all source files are compiled into .o files as normal. Then instead of including all .o files in the linker command directly, all .o files are saved into a .a file, which is then included in the linker command. [1.5 format library folder structure](#layout-of-folders-and-files) is required. -* **includes** - **(available from Arduino IDE 1.6.10)** (optional) a comma separated list of files to be added to the sketch as `#include <...>` lines. This property is used with the "Include library" command in the Arduino IDE. If the `includes` property is missing, all the header files (.h) on the root source folder are included. -* **precompiled** - **(available from Arduino IDE 1.8.6/arduino-builder 1.4.0)** (optional) set to `true` to allow the use of .a (archive) and .so (shared object) files. The .a/.so file must be located at `src/{build.mcu}` where `{build.mcu}` is the architecture name of the target the file was compiled for. Ex: `cortex-m3` for the Arduino DUE. The static library should be linked as an ldflag. -* **ldflags** - **(available from Arduino IDE 1.8.6/arduino-builder 1.4.0)** (optional) the linker flags to be added. Ex: `ldflags=-lm` +The library.properties file is a key=value properties list. Every field in this file is UTF-8 encoded. Unless noted +otherwise below, **all fields are required**. The available fields are: + +- **name** - the name of the library. Library names must contain only basic letters (A-Z or a-z) and numbers (0-9), + spaces ( ), underscores (\_), dots (.) and dashes (-). They cannot start with a number. Note that libraries with a + `name` value starting with `Arduino` will no longer be allowed + [addition to the Library Manager index](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ) as these names + are now reserved for official Arduino libraries. +- **version** - version of the library. Version should be [semver](http://semver.org/) compliant. 1.2.0 is correct; 1.2 + is accepted; r5, 003, 1.1c are invalid +- **author** - name/nickname of the authors and their email addresses (not mandatory) separated by comma "," +- **maintainer** - name and email of the maintainer +- **sentence** - a sentence explaining the purpose of the library +- **paragraph** - a longer description of the library. The value of **sentence** always will be prepended, so you should + start by writing the second sentence here +- **category** - (defaults to `Uncategorized`) if present, one of these: + - Display + - Communication + - Signal Input/Output + - Sensors + - Device Control + - Timing + - Data Storage + - Data Processing + - Other +- **url** - the URL of the library project, for a person to visit. For example, the library's GitHub page. This is used + for the "More info" links in Library Manager +- **architectures** - (defaults to `*`) a comma separated list of architectures supported by the library. If the library + doesn’t contain architecture specific code use `*` to match all architectures. This field is used as one factor in + determining priority when multiple libraries match an `#include` directive and to provide a warning message when the + library is compiled for a board of an architecture that doesn't match any on the list. +- **depends** - **(available from Arduino IDE 1.8.10/Arduino CLI 0.7.0)** (optional) a comma-separated list of + dependencies (libraries that are needed to build the current library). The Arduino IDE's Library Manager will offer to + install the dependencies during installation of the library. + [`arduino-cli lib install`](../commands/arduino-cli_lib_install) will automatically install the dependencies. Since + spaces are allowed in the `name` of a library, but not commas, you can refer to libraries containing spaces in the + name without ambiguity for example:
`depends=Very long library name, Another library with long-name` +- **dot_a_linkage** - **(available from Arduino IDE 1.6.0 / arduino-builder 1.0.0-beta13)** (optional) when set to + `true`, the library will be compiled using a .a (archive) file. First, all source files are compiled into .o files as + normal. Then instead of including all .o + + files in the linker command directly, all .o files are saved into a .a file, which is then included in the linker + command. [1.5 format library folder structure](#layout-of-folders-and-files) is required. +- **includes** - **(available from Arduino IDE 1.6.10)** (optional) a comma separated list of files to be added to the + sketch as `#include <...>` lines. This property is used with the "Include library" command in the Arduino IDE. If the + `includes` property is missing, all the header files (.h) on the root source folder are included. +- **precompiled** - **(available from Arduino IDE 1.8.6/arduino-builder 1.4.0)** (optional) set to `true` to allow the + use of .a (archive) and .so (shared object) files. The .a/.so file must be located at `src/{build.mcu}` where + `{build.mcu}` is the architecture name of the target the file was compiled for. Ex: `cortex-m3` for the Arduino DUE. + The static library should be linked as an ldflag. +- **ldflags** - **(available from Arduino IDE 1.8.6/arduino-builder 1.4.0)** (optional) the linker flags to be added. + Ex: `ldflags=-lm` Example: @@ -69,11 +105,13 @@ Example: ### Layout of folders and files -Each folder has a specific purpose (sources, examples, documentation, etc). Folders not covered in this specification may be added as needed to future revisions. +Each folder has a specific purpose (sources, examples, documentation, etc). Folders not covered in this specification +may be added as needed to future revisions. #### Library Root folder -The library root folder name must start with a basic letter (`A`-`Z` or `a`-`z`) or number (`0`-`9`), followed by basic letters, numbers, spaces (` `), underscores (`_`), dots (`.`) and dashes (`-`). The maximum length is 63 characters. +The library root folder name must start with a basic letter (A-Z or a-z) or number (0-9), followed by basic letters, +numbers, spaces ( ), underscores (\_), dots (.) and dashes (-). The maximum length is 63 characters. #### Source code @@ -82,43 +120,63 @@ For 1.5.x+-only libraries, the source code resides in the **src** folder. For ex Servo/src/Servo.h Servo/src/Servo.cpp -The source code found in **src** folder and *all its subfolders* is compiled and linked in the user’s sketch. Only the *src* folder is added to the include search path (both when compiling the sketch and the library). When the user imports a library into their sketch (from the Arduino IDE's "Sketch > Include Library" menu or the Arduino Web Editor's "Include" button), the default behavior (configurable via the [library.properties `includes` field](#libraryproperties-file-format)) is for an `#include` statement to be added for all header (.h) files in the src/ directory (but not its subfolders). As a result, these header files form something of a de facto interface to your library; in general, the only header files in the root src/ folder should be those that you want to expose to the user's sketch and plan to maintain compatibility with in future versions of the library. Place internal header files in a subfolder of the src/ folder. +The source code found in **src** folder and _all its subfolders_ is compiled and linked in the user’s sketch. Only the +_src_ folder is added to the include search path (both when compiling the sketch and the library). When the user imports +a library into their sketch (from the Arduino IDE's "Sketch > Include Library" menu or the Arduino Web Editor's +"Include" button), the default behavior (configurable via the +[library.properties `includes` field](#libraryproperties-file-format)) is for an `#include` statement to be added for +all header (.h) files in the src/ directory (but not its subfolders). As a result, these header files form something of +a de facto interface to your library; in general, the only header files in the root src/ folder should be those that you +want to expose to the user's sketch and plan to maintain compatibility with in future versions of the library. Place +internal header files in a subfolder of the src/ folder. -For backward compatibility with Arduino IDE 1.0.x, the library author may opt to place source code into the root folder, instead of the folder called **src**. In this case the 1.0 library format is applied and the source code is searched from the **library root folder** and the **utility** folder, for example: +For backward compatibility with Arduino IDE 1.0.x, the library author may opt to place source code into the root folder, +instead of the folder called **src**. In this case the 1.0 library format is applied and the source code is searched +from the **library root folder** and the **utility** folder, for example: Servo/Servo.h Servo/Servo.cpp Servo/utility/ServoTimers.h Servo/utility/ServoTimers.cpp -This will allow existing 1.0 format libraries to compile under Arduino IDE 1.5.x+ as well and vice-versa. If a library only needs to run on Arduino IDE 1.5.x+, we recommend placing all source code in the src/ folder. If a library requires recursive compilation of nested source folders, its code must be in the src/ folder (since Arduino IDE 1.0.x doesn’t support recursive compilation, backwards compatibility wouldn’t be possible anyway). +This will allow existing 1.0 format libraries to compile under Arduino IDE 1.5.x+ as well and vice-versa. If a library +only needs to run on Arduino IDE 1.5.x+, we recommend placing all source code in the src/ folder. If a library requires +recursive compilation of nested source folders, its code must be in the src/ folder (since Arduino IDE 1.0.x doesn’t +support recursive compilation, backwards compatibility wouldn’t be possible anyway). #### Library Examples -Library examples must be placed in the **examples** folder. Note that the **examples** folder must be written exactly like that (with lower case letters). +Library examples must be placed in the **examples** folder. Note that the **examples** folder must be written exactly +like that (with lower case letters). Servo/examples/... -Sketches contained inside the examples folder will be shown in the Examples menu of the Arduino IDE and Arduino Web Editor. +Sketches contained inside the examples folder will be shown in the Examples menu of the Arduino IDE and Arduino Web +Editor. More information: -* [Arduino sketch specification](sketch-specification.md) -* [Style guide for Arduino examples](http://arduino.cc/en/Reference/StyleGuide) +- [Arduino sketch specification](sketch-specification.md) +- [Style guide for Arduino examples](http://arduino.cc/en/Reference/StyleGuide) #### Extra documentation -An **extras** folder can be used by the developer to put documentation or other items to be bundled with the library. Remember that files placed inside this folder will increase the size of the library, so putting a 20MB PDF in a library that weights a few kilobytes may not be such a good idea. +An **extras** folder can be used by the developer to put documentation or other items to be bundled with the library. +Remember that files placed inside this folder will increase the size of the library, so putting a 20MB PDF in a library +that weights a few kilobytes may not be such a good idea. -The content of the *extras* folder is totally ignored by the Arduino development software; you are free to put anything inside such as supporting documentation, etc. +The content of the _extras_ folder is totally ignored by the Arduino development software; you are free to put anything +inside such as supporting documentation, etc. ### Keywords -A list of keywords for the library may be specified in a file named keywords.txt located in the root of the library folder. When a keyword of any installed library is used in a sketch the Arduino IDE colors it. +A list of keywords for the library may be specified in a file named keywords.txt located in the root of the library +folder. When a keyword of any installed library is used in a sketch the Arduino IDE colors it. Servo/keywords.txt An example keywords.txt file: + ``` # Syntax Coloring Map For ExampleLibrary @@ -132,40 +190,57 @@ doSomething KEYWORD2 # Constants (LITERAL1) ``` + This file would cause the Arduino IDE to highlight `Test` as a DataType, and `doSomething` as a method / function. #### keywords.txt format + keywords.txt is formatted in four fields which are separated by a single true tab (not spaces): + ``` KEYWORD KEYWORD_TOKENTYPE REFERENCE_LINK RSYNTAXTEXTAREA_TOKENTYPE ``` + It is permitted to leave a field empty. + ##### `KEYWORD_TOKENTYPE` -KEYWORD_TOKENTYPE | Use for | Theme property ----|---|--- -`KEYWORD1` | datatypes | `editor.data_type.style` -`KEYWORD2` | functions | `editor.function.style` -`KEYWORD3` | structures | `editor.function.style` -`LITERAL1` | constants | `editor.reserved_word_2.style` -`LITERAL2` | ? | `editor.function.style` + +| KEYWORD_TOKENTYPE | Use for | Theme property | +| ----------------- | ---------- | ------------------------------ | +| `KEYWORD1` | datatypes | `editor.data_type.style` | +| `KEYWORD2` | functions | `editor.function.style` | +| `KEYWORD3` | structures | `editor.function.style` | +| `LITERAL1` | constants | `editor.reserved_word_2.style` | +| `LITERAL2` | ? | `editor.function.style` | ##### `REFERENCE_LINK` -This field specifies the [Arduino Language Reference](https://www.arduino.cc/reference/en) page to open via the Arduino IDE's **Right Click > Find in Reference** or **Help > Find in Reference** when the cursor is on that keyword. Generally it does not make sense to define the `REFERENCE_LINK` field for 3rd party library keywords since they are not likely to be in the Arduino Language Reference. + +This field specifies the [Arduino Language Reference](https://www.arduino.cc/reference/en) page to open via the Arduino +IDE's **Right Click > Find in Reference** or **Help > Find in Reference** when the cursor is on that keyword. Generally +it does not make sense to define the `REFERENCE_LINK` field for 3rd party library keywords since they are not likely to +be in the Arduino Language Reference. ##### `RSYNTAXTEXTAREA_TOKENTYPE` -In Arduino IDE 1.6.5 and newer this field overrides `KEYWORD_TOKENTYPE`. In previous IDE versions the `RSYNTAXTEXTAREA_TOKENTYPE` field is ignored and `KEYWORD_TOKENTYPE` is used instead. -RSYNTAXTEXTAREA_TOKENTYPE | Theme property | KEYWORD_TOKENTYPE equivalent ----|---|--- -`RESERVED_WORD` | `editor.reserved_word.style` | `KEYWORD3` -`RESERVED_WORD_2` | `editor.reserved_word_2.style` | `LITERAL1` -`DATA_TYPE` | `editor.data_type.style` | `KEYWORD1` -`PREPROCESSOR` | `editor.preprocessor.style` | `KEYWORD3` -`LITERAL_BOOLEAN` | `editor.literal_boolean.style` | `LITERAL1` +In Arduino IDE 1.6.5 and newer this field overrides `KEYWORD_TOKENTYPE`. In previous IDE versions the +`RSYNTAXTEXTAREA_TOKENTYPE` field is ignored and `KEYWORD_TOKENTYPE` is used instead. + +| RSYNTAXTEXTAREA_TOKENTYPE | Theme property | KEYWORD_TOKENTYPE equivalent | +| ------------------------- | ------------------------------ | ---------------------------- | +| `RESERVED_WORD` | `editor.reserved_word.style` | `KEYWORD3` | +| `RESERVED_WORD_2` | `editor.reserved_word_2.style` | `LITERAL1` | +| `DATA_TYPE` | `editor.data_type.style` | `KEYWORD1` | +| `PREPROCESSOR` | `editor.preprocessor.style` | `KEYWORD3` | +| `LITERAL_BOOLEAN` | `editor.literal_boolean.style` | `LITERAL1` | ### Development flag file -Normally the Arduino IDE treats the contents of the library folder as read-only. This is to prevent users from accidentally modifying example sketches. During the library development process you may want to edit example sketches in place using the Arduino IDE. With Arduino IDE 1.6.6 and newer, the read-only behavior can be disabled by adding a file named .development to the root of the library folder. A [library.properties](#libraryproperties-file-format) file must also be present. The [Library Manager indexer](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ) will not pick up releases that contain a .development file so be sure not to push this file to your remote repository. +Normally the Arduino IDE treats the contents of the library folder as read-only. This is to prevent users from +accidentally modifying example sketches. During the library development process you may want to edit example sketches in +place using the Arduino IDE. With Arduino IDE 1.6.6 and newer, the read-only behavior can be disabled by adding a file +named .development to the root of the library folder. A [library.properties](#libraryproperties-file-format) file must +also be present. The [Library Manager indexer](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ) will not +pick up releases that contain a .development file so be sure not to push this file to your remote repository. ### A complete example @@ -186,7 +261,11 @@ A hypothetical library named "Servo" that adheres to the specification follows: ## Working with multiple architectures -Libraries placed in the `libraries` subfolder of the sketchbook folder (AKA "user directory") will be made available for all boards, which may include multiple different processor architectures. To provide architecture-specific code or optimizations, library authors can use the `ARDUINO_ARCH_XXX` preprocessor macro (`#define`), where XXX is the name of the architecture (as determined by the name of the folder containing it), e.g. `ARDUINO_ARCH_AVR` will be defined when compiling for AVR-based boards. For example, +Libraries placed in the `libraries` subfolder of the sketchbook folder (AKA "user directory") will be made available for +all boards, which may include multiple different processor architectures. To provide architecture-specific code or +optimizations, library authors can use the `ARDUINO_ARCH_XXX` preprocessor macro (`#define`), where XXX is the name of +the architecture (as determined by the name of the folder containing it), e.g. `ARDUINO_ARCH_AVR` will be defined when +compiling for AVR-based boards. For example, #if defined(ARDUINO_ARCH_AVR) // AVR-specific code @@ -196,7 +275,8 @@ Libraries placed in the `libraries` subfolder of the sketchbook folder (AKA "use // generic, non-platform specific code #endif -Alternatively, if a library only works on certain architectures, you can provide an explicit error message (instead of allowing the compilation to fail in a difficult to understand way): +Alternatively, if a library only works on certain architectures, you can provide an explicit error message (instead of +allowing the compilation to fail in a difficult to understand way): #if defined(ARDUINO_ARCH_AVR) // AVR-specific code @@ -208,4 +288,7 @@ Alternatively, if a library only works on certain architectures, you can provide ## Old library format (pre-1.5) -In order to support old libraries (from Arduino IDE 1.0.x), the Arduino IDE/Pro IDE and Arduino CLI will also compile libraries missing a library.properties metadata file. As a result, these libraries should behave as they did in Arduino IDE 1.0.x, although they will be available for all boards, including non-AVR ones (which wouldn’t have been present in Arduino IDE 1.0.x). +In order to support old libraries (from Arduino IDE 1.0.x), the Arduino IDE/Pro IDE and Arduino CLI will also compile +libraries missing a library.properties metadata file. As a result, these libraries should behave as they did in Arduino +IDE 1.0.x, although they will be available for all boards, including non-AVR ones (which wouldn’t have been present in +Arduino IDE 1.0.x). diff --git a/docs/package_index_json-specification.md b/docs/package_index_json-specification.md index de8f693b82b..ea5ad3c0613 100644 --- a/docs/package_index_json-specification.md +++ b/docs/package_index_json-specification.md @@ -1,15 +1,20 @@ -Introduced in Arduino IDE 1.6.4, Boards Manager makes it easy to install and update Arduino platforms. In order to provide Boards Manager installation support for a platform, a JSON formatted index file must be published. This is the specification for that file. +Introduced in Arduino IDE 1.6.4, Boards Manager makes it easy to install and update Arduino platforms. In order to +provide Boards Manager installation support for a platform, a JSON formatted index file must be published. This is the +specification for that file. -Boards Manager functionality is provided by [Arduino CLI](getting-started.md#adding-3rd-party-cores), [Arduino IDE](https://www.arduino.cc/en/Guide/Cores), and Arduino Pro IDE. +Boards Manager functionality is provided by [Arduino CLI](getting-started.md#adding-3rd-party-cores), +[Arduino IDE](https://www.arduino.cc/en/Guide/Cores), and Arduino Pro IDE. ## Naming of the JSON index file -Many different index files coming from different vendors may be in use, so each vendor should name their own index file in a way that won't conflict with others. The file must be named as follows: +Many different index files coming from different vendors may be in use, so each vendor should name their own index file +in a way that won't conflict with others. The file must be named as follows: `package_YOURNAME_PACKAGENAME_index.json` -The prefix `package_` and the postfix `_index.json` are **mandatory** (otherwise the index file is not recognised by the Arduino development software) while the choice of `YOURNAME_PACKAGENAME` is left to the packager. -We suggest using a domain name owned by the packager. For example: +The prefix `package_` and the postfix `_index.json` are **mandatory** (otherwise the index file is not recognised by the +Arduino development software) while the choice of `YOURNAME_PACKAGENAME` is left to the packager. We suggest using a +domain name owned by the packager. For example: `package_arduino.cc_index.json` @@ -17,7 +22,8 @@ or `package_example.com_avr_boards_index.json` -The index URL is periodically checked for updates so expect a constant flow of downloads (proportional to the number of active users). +The index URL is periodically checked for updates so expect a constant flow of downloads (proportional to the number of +active users). ## JSON Index file contents @@ -25,14 +31,14 @@ The root of the JSON index is an array of `packages`: ```json { - "packages": [ - PACKAGE_XXXX - ] + "packages": [PACKAGE_XXXX] } ``` -3rd party vendors should use a single `PACKAGE_XXXX` that is a dictionary map with the vendor's metadata, a list of `PLATFORMS` and a list of `TOOLS`. For example: +3rd party vendors should use a single `PACKAGE_XXXX` that is a dictionary map with the vendor's metadata, a list of +`PLATFORMS` and a list of `TOOLS`. For example: + ```json { "name": "arduino", @@ -40,29 +46,28 @@ The root of the JSON index is an array of `packages`: "websiteURL": "http://www.arduino.cc/", "email": "packages@arduino.cc", - "platforms": [ - PLATFORM_AVR, - PLATFORM_ARM, - PLATFORM_XXXXX, - PLATFORM_YYYYY, - ], + "platforms": [PLATFORM_AVR, PLATFORM_ARM, PLATFORM_XXXXX, PLATFORM_YYYYY], "tools": [ TOOLS_COMPILER_AVR, TOOLS_UPLOADER_AVR, TOOLS_COMPILER_ARM, TOOLS_XXXXXXX, - TOOLS_YYYYYYY, - ], + TOOLS_YYYYYYY + ] } + ``` The metadata fields are: -* `name`: the folder used for the installed cores. The [vendor folder](platform-specification.md#hardware-folders-structure) name of the installed package is determined by this field -* `maintainer`: the extended name of the vendor that is displayed on the Arduino IDE/Pro IDE's Boards Manager GUI -* `websiteURL`: the URL to the vendor's website, appears on the Arduino IDE/Pro IDE's Boards Manager as a "More info" link -* `email`: the email of the vendor/maintainer +- `name`: the folder used for the installed cores. The + [vendor folder](platform-specification.md#hardware-folders-structure) name of the installed package is determined by + this field +- `maintainer`: the extended name of the vendor that is displayed on the Arduino IDE/Pro IDE's Boards Manager GUI +- `websiteURL`: the URL to the vendor's website, appears on the Arduino IDE/Pro IDE's Boards Manager as a "More info" + link +- `email`: the email of the vendor/maintainer Now, before looking at `PLATFORMS`, let's explore first how `TOOLS` are made. @@ -70,11 +75,11 @@ Now, before looking at `PLATFORMS`, let's explore first how `TOOLS` are made. Each tool describes a binary distribution of a command line tool. A tool can be: -* a compiler toolchain -* an uploader -* a file preprocessor -* a debugger -* a program that performs a firmware upgrade +- a compiler toolchain +- an uploader +- a file preprocessor +- a debugger +- a program that performs a firmware upgrade basically anything that can run on the user's host PC and do something useful. @@ -119,43 +124,51 @@ Tools are mapped as JSON in this way: }, ``` -The field `name` and `version` are respectively the name and version of the tool. -Each tool is uniquely identified by the triple (`vendor`, `name`, `version`) and there can be many different versions of the same tool available at the same time, for example: +The field `name` and `version` are respectively the name and version of the tool. Each tool is uniquely identified by +the triple (`vendor`, `name`, `version`) and there can be many different versions of the same tool available at the same +time, for example: -* (`arduino`, `avr-gcc`, `4.8.1-arduino2`) -* (`arduino`, `avr-gcc`, `4.8.1-arduino3`) -* (`arduino`, `avr-gcc`, `4.8.1-arduino5`) -* (`arduino`, `avrdude`, `5.11`) -* (`arduino`, `avrdude`, `6.0`) -* (`arduino`, `avrdude`, `6.1`) -* ..... +- (`arduino`, `avr-gcc`, `4.8.1-arduino2`) +- (`arduino`, `avr-gcc`, `4.8.1-arduino3`) +- (`arduino`, `avr-gcc`, `4.8.1-arduino5`) +- (`arduino`, `avrdude`, `5.11`) +- (`arduino`, `avrdude`, `6.0`) +- (`arduino`, `avrdude`, `6.1`) +- ..... -Each tool version may come in different build flavours for different OS. Each flavour is listed under the `systems` array. In the example above `avr-gcc` comes with builds for: +Each tool version may come in different build flavours for different OS. Each flavour is listed under the `systems` +array. In the example above `avr-gcc` comes with builds for: -* Linux 64-bit (`x86_64-linux-gnu`), -* Linux 32-bit (`i686-linux-gnu`), -* Windows (`i686-mingw32`), -* Mac (`i386-apple-darwin11`) +- Linux 64-bit (`x86_64-linux-gnu`), +- Linux 32-bit (`i686-linux-gnu`), +- Windows (`i686-mingw32`), +- Mac (`i386-apple-darwin11`) -The IDE will take care to install the right flavour based on the `host` value, or fail if a needed flavour is missing.
-Note that this information is not used to select the toolchain during compilation. If you want this specific version to be used, you should use the notation {runtime.tools.TOOLNAME-VERSION.path} in the platform.txt. +The IDE will take care to install the right flavour based on the `host` value, or fail if a needed flavour is +missing.
Note that this information is not used to select the toolchain during compilation. If you want this +specific version to be used, you should use the notation {runtime.tools.TOOLNAME-VERSION.path} in the platform.txt. The other fields are: -* `url`: the download URL of the tool's archive -* `archiveFileName`: the name of the file saved to disk after the download (some web servers don't provide the filename through the HTTP request) -* `size`: the size of the archive in bytes -* `checksum`: the checksum of the archive, used to check if the file has been corrupted. The format is `ALGORITHM:CHECKSUM`, currently `MD5`, `SHA-1`,`SHA-256` algorithm are supported, we recommend `SHA-256`. On *nix or MacOSX you may be able to use the command `shasum -a 256 filename` to generate SHA-256 checksums. There are many free options for Windows including md5deep, there are also online utilities for generating checksums. +- `url`: the download URL of the tool's archive +- `archiveFileName`: the name of the file saved to disk after the download (some web servers don't provide the filename + through the HTTP request) +- `size`: the size of the archive in bytes +- `checksum`: the checksum of the archive, used to check if the file has been corrupted. The format is + `ALGORITHM:CHECKSUM`, currently `MD5`, `SHA-1`,`SHA-256` algorithm are supported, we recommend `SHA-256`. On \*nix or + MacOSX you may be able to use the command `shasum -a 256 filename` to generate SHA-256 checksums. There are many free + options for Windows including md5deep, there are also online utilities for generating checksums. ##### How a tool's path is determined in platform.txt -When the IDE needs a tool it downloads the corresponding archive file and unpacks the content into -a private folder that can be referenced from `platform.txt` using one of the following properties: +When the IDE needs a tool it downloads the corresponding archive file and unpacks the content into a private folder that +can be referenced from `platform.txt` using one of the following properties: -* `{runtime.tools.TOOLNAME-VERSION.path}` -* `{runtime.tools.TOOLNAME.path}` +- `{runtime.tools.TOOLNAME-VERSION.path}` +- `{runtime.tools.TOOLNAME.path}` -For example to obtain the avr-gcc 4.8.1 folder we can use `{runtime.tools.avr-gcc-4.8.1-arduino5.path}` or `{runtime.tools.avr-gcc.path}`. +For example to obtain the avr-gcc 4.8.1 folder we can use `{runtime.tools.avr-gcc-4.8.1-arduino5.path}` or +`{runtime.tools.avr-gcc.path}`. ### Platforms definitions @@ -192,23 +205,32 @@ Finally, let's see how `PLATFORMS` are made. Each PLATFORM describes a core for a specific architecture. The fields needed are: -* `name`: the extended name of the platform that is displayed on the Boards Manager GUI -* `architecture`: is the architecture of the platform (avr, sam, etc...). It must match the architecture of the core as explained in the [Arduino platform specification](platform-specification.md#hardware-folders-structure) -* `version`: the version of the platform. -* `category`: this field is reserved, a 3rd party core must set it to `Contributed` -* `help`/`online`: is a URL that is displayed on the Arduino IDE's Boards Manager as an "Online Help" link -* `url`, `archiveFileName`, `size` and `checksum`: metadata of the core archive file. The meaning is the same as for the TOOLS -* `boards`: the list of boards supported (note: just the names to display on the Arduino IDE and Arduino Pro IDE's Boards Manager GUI! the real boards definitions are inside `boards.txt` inside the core archive file) -* `toolsDependencies`: the tools needed by this core. Each tool is referenced by the triple (`packager`, `name`, `version`) as previously said. Note that you can reference tools available in other packages as well. - -The `version` field is validated by both Arduino IDE and [JSemVer](https://github.com/zafarkhaja/jsemver). Here are the rules Arduino IDE follows for parsing versions ([source](https://github.com/arduino/Arduino/blob/master/arduino-core/src/cc/arduino/contributions/VersionHelper.java)): - -* Split the version at the - character and continue with the first part. -* If there are no dots (`.`), parse `version` as an integer and form a Version from that integer using `Version.forIntegers` -* If there is one dot, split `version` into two, parse each part as an integer, and form a Version from those integers using `Version.forIntegers` -* Otherwise, simply parse `version` into a Version using `Version.valueOf` - -Note: if you miss a bracket in the JSON index, then add the URL to your Preferences, and open Boards Manager it can cause the Arduino IDE to no longer load until you have deleted the file from your arduino15 folder. +- `name`: the extended name of the platform that is displayed on the Boards Manager GUI +- `architecture`: is the architecture of the platform (avr, sam, etc...). It must match the architecture of the core as + explained in the [Arduino platform specification](platform-specification.md#hardware-folders-structure) +- `version`: the version of the platform. +- `category`: this field is reserved, a 3rd party core must set it to `Contributed` +- `help`/`online`: is a URL that is displayed on the Arduino IDE's Boards Manager as an "Online Help" link +- `url`, `archiveFileName`, `size` and `checksum`: metadata of the core archive file. The meaning is the same as for the + TOOLS +- `boards`: the list of boards supported (note: just the names to display on the Arduino IDE and Arduino Pro IDE's + Boards Manager GUI! the real boards definitions are inside `boards.txt` inside the core archive file) +- `toolsDependencies`: the tools needed by this core. Each tool is referenced by the triple (`packager`, `name`, + `version`) as previously said. Note that you can reference tools available in other packages as well. + +The `version` field is validated by both Arduino IDE and [JSemVer](https://github.com/zafarkhaja/jsemver). Here are the +rules Arduino IDE follows for parsing versions +([source](https://github.com/arduino/Arduino/blob/master/arduino-core/src/cc/arduino/contributions/VersionHelper.java)): + +- Split the version at the - character and continue with the first part. +- If there are no dots (`.`), parse `version` as an integer and form a Version from that integer using + `Version.forIntegers` +- If there is one dot, split `version` into two, parse each part as an integer, and form a Version from those integers + using `Version.forIntegers` +- Otherwise, simply parse `version` into a Version using `Version.valueOf` + +Note: if you miss a bracket in the JSON index, then add the URL to your Preferences, and open Boards Manager it can +cause the Arduino IDE to no longer load until you have deleted the file from your arduino15 folder. ### Example JSON index file @@ -236,10 +258,7 @@ Note: if you miss a bracket in the JSON index, then add the URL to your Preferen "archiveFileName": "myboard-1.0.0.zip", "checksum": "SHA-256:ec3ff8a1dc96d3ba6f432b9b837a35fd4174a34b3d2927de1d51010e8b94f9f1", "size": "15005", - "boards": [ - {"name": "My Board"}, - {"name": "My Board Pro"} - ], + "boards": [{ "name": "My Board" }, { "name": "My Board Pro" }], "toolsDependencies": [ { "packager": "arduino", @@ -265,10 +284,7 @@ Note: if you miss a bracket in the JSON index, then add the URL to your Preferen "archiveFileName": "myboard-1.0.1.zip", "checksum": "SHA-256:9c86ee28a7ce9fe33e8b07ec643316131e0031b0d22e63bb398902a5fdadbca9", "size": "15125", - "boards": [ - {"name": "My Board"}, - {"name": "My Board Pro"} - ], + "boards": [{ "name": "My Board" }, { "name": "My Board Pro" }], "toolsDependencies": [ { "packager": "arduino", @@ -283,22 +299,26 @@ Note: if you miss a bracket in the JSON index, then add the URL to your Preferen ] } ], - "tools":[] + "tools": [] } ] } ``` -In the example there is one `PACKAGE`, My Board. The package is compatible with the AVR architecture. There are two versions of the `PACKAGE`, 1.0.0 and 1.0.1. No `TOOLS` needed to be installed so that section was left blank. -Here is the Boards Manager entry created by the example: -![Boards Manager screenshot](img/boards-manager-screenshot.png) +In the example there is one `PACKAGE`, My Board. The package is compatible with the AVR architecture. There are two +versions of the `PACKAGE`, 1.0.0 and 1.0.1. No `TOOLS` needed to be installed so that section was left blank. + +Here is the Boards Manager entry created by the example: ![Boards Manager screenshot](img/boards-manager-screenshot.png) ## Installation archive structure The installation archives contain the Board support files. Supported formats are .zip, .tar.bz2, and .tar.gz. -The folder structure of the core archive is slightly different from the standard manually installed Arduino IDE 1.5+ compatible hardware folder structure. You must remove the architecture folder(e.g., `avr` or `arm`), moving all the files and folders within the architecture folder up a level. +The folder structure of the core archive is slightly different from the standard manually installed Arduino IDE 1.5+ +compatible hardware folder structure. You must remove the architecture folder(e.g., `avr` or `arm`), moving all the +files and folders within the architecture folder up a level. -*** +--- -After adding Boards Manager support for your boards, please share the JSON index file URL on the [Unofficial list of 3rd party boards support urls](https://github.com/arduino/Arduino/wiki/Unofficial-list-of-3rd-party-boards-support-urls). +After adding Boards Manager support for your boards, please share the JSON index file URL on the +[Unofficial list of 3rd party boards support urls](https://github.com/arduino/Arduino/wiki/Unofficial-list-of-3rd-party-boards-support-urls). diff --git a/docs/platform-specification.md b/docs/platform-specification.md index 9c2cadc0b15..3f96c7f3858 100644 --- a/docs/platform-specification.md +++ b/docs/platform-specification.md @@ -1,15 +1,17 @@ -This is the Arduino platform specification, for use with Arduino development software starting from the Arduino IDE 1.5.x series.
-Platforms add support for new boards to the Arduino development software. They are installable either via [Boards Manager](package_index_json-specification.md) or manual installation to the *hardware* folder of Arduino's sketchbook folder (AKA "user directory").
-A platform may consist of as little as a single configuration file. +This is the Arduino platform specification, for use with Arduino development software starting from the Arduino IDE +1.5.x series.
Platforms add support for new boards to the Arduino development software. They are installable either +via [Boards Manager](package_index_json-specification.md) or manual installation to the _hardware_ folder of Arduino's +sketchbook folder (AKA "user directory").
A platform may consist of as little as a single configuration file. ## Hardware Folders structure The new hardware folders have a hierarchical structure organized in two levels: - - the first level is the vendor/maintainer - - the second level is the supported architecture +- the first level is the vendor/maintainer +- the second level is the supported architecture -A vendor/maintainer can have multiple supported architectures. For example, below we have three hardware vendors called "arduino", "yyyyy" and "xxxxx": +A vendor/maintainer can have multiple supported architectures. For example, below we have three hardware vendors called +"arduino", "yyyyy" and "xxxxx": hardware/arduino/avr/... - Arduino - AVR Boards hardware/arduino/sam/... - Arduino - SAM (32bit ARM) Boards @@ -18,26 +20,34 @@ A vendor/maintainer can have multiple supported architectures. For example, belo The vendor "arduino" has two supported architectures (AVR and SAM), while "xxxxx" and "yyyyy" have only AVR. -If possible, follow existing architecture name conventions when creating hardware packages. The architecture folder name is used to determine library compatibility and also to permit referencing resources from another core of the same architecture so using a non-standard architecture name can only be harmful to your users. Architecture values are case sensitive (e.g. `AVR` != `avr`). Use the vendor folder name to differentiate your package, **NOT** the architecture name. +If possible, follow existing architecture name conventions when creating hardware packages. The architecture folder name +is used to determine library compatibility and also to permit referencing resources from another core of the same +architecture so using a non-standard architecture name can only be harmful to your users. Architecture values are case +sensitive (e.g. `AVR` != `avr`). Use the vendor folder name to differentiate your package, **NOT** the architecture +name. ## Architecture configurations Each architecture must be configured through a set of configuration files: -* **platform.txt** contains definitions for the CPU architecture used (compiler, build process parameters, tools used for upload, etc.) -* **boards.txt** contains definitions for the boards (board name, parameters for building and uploading sketches, etc.) -* **programmers.txt** contains definitions for external programmers (typically used to burn bootloaders or sketches on a blank CPU/board) +- **platform.txt** contains definitions for the CPU architecture used (compiler, build process parameters, tools used + for upload, etc.) +- **boards.txt** contains definitions for the boards (board name, parameters for building and uploading sketches, etc.) +- **programmers.txt** contains definitions for external programmers (typically used to burn bootloaders or sketches on a + blank CPU/board) ### Configuration files format -A configuration file is a list of "key=value" properties. The **value** of a property can be expressed using the value of another property by putting its name inside brackets "{" "}". For example: +A configuration file is a list of "key=value" properties. The **value** of a property can be expressed using the value +of another property by putting its name inside brackets "{" "}". For example: compiler.path=/tools/g++_arm_none_eabi/bin/ compiler.c.cmd=arm-none-eabi-gcc [....] recipe.c.o.pattern={compiler.path}{compiler.c.cmd} -In this example the property **recipe.c.o.pattern** will be set to **/tools/g++_arm_none_eabi/bin/arm-none-eabi-gcc** that is the composition of the two properties **compiler.path** and **compiler.c.cmd**. +In this example the property **recipe.c.o.pattern** will be set to **/tools/g++\_arm_none_eabi/bin/arm-none-eabi-gcc** +that is the composition of the two properties **compiler.path** and **compiler.c.cmd**. #### Comments @@ -54,65 +64,82 @@ We can specify an OS-specific value for a property. For example the following fi tools.bossac.cmd=bossac tools.bossac.cmd.windows=bossac.exe -will set the property **tools.bossac.cmd** to the value **bossac** on Linux and Mac OS and **bossac.exe** on Windows. Suffixes [supported](https://github.com/arduino/Arduino/blob/1.8.12/arduino-core/src/processing/app/helpers/PreferencesMap.java#L110-L112) are `.linux`, `.windows` and `.macosx`. +will set the property **tools.bossac.cmd** to the value **bossac** on Linux and Mac OS and **bossac.exe** on Windows. +Suffixes +[supported](https://github.com/arduino/Arduino/blob/1.8.12/arduino-core/src/processing/app/helpers/PreferencesMap.java#L110-L112) +are `.linux`, `.windows` and `.macosx`. #### Global Predefined properties The following automatically generated properties can be used globally in all configuration files: -* `{runtime.platform.path}`: the absolute path of the [board platform](#platform-terminology) folder (i.e. the folder containing boards.txt) -* `{runtime.hardware.path}`: the absolute path of the hardware folder (i.e. the folder containing the [board platform](#platform-terminology) folder) -* `{runtime.ide.path}`: the absolute path of the Arduino IDE or Arduino CLI folder -* `{runtime.ide.version}`: the version number of the Arduino IDE as a number (this uses two digits per version number component, and removes the points and leading zeroes, so Arduino IDE 1.8.3 becomes `01.08.03` which becomes `runtime.ide.version=10803`). When using Arduino development software other than the Arduino IDE, this is set to a meaningless version number. -* `{ide_version}`: Compatibility alias for `{runtime.ide.version}` -* `{runtime.os}`: the running OS ("linux", "windows", "macosx") - -Compatibility note: Versions before Arduino IDE 1.6.0 only used one digit per version number component in `{runtime.ide.version}` (so 1.5.9 was `159`, not `10509`). +- `{runtime.platform.path}`: the absolute path of the [board platform](#platform-terminology) folder (i.e. the folder + containing boards.txt) +- `{runtime.hardware.path}`: the absolute path of the hardware folder (i.e. the folder containing the + [board platform](#platform-terminology) folder) +- `{runtime.ide.path}`: the absolute path of the Arduino IDE or Arduino CLI folder +- `{runtime.ide.version}`: the version number of the Arduino IDE as a number (this uses two digits per version number + component, and removes the points and leading zeroes, so Arduino IDE 1.8.3 becomes `01.08.03` which becomes + `runtime.ide.version=10803`). When using Arduino development software other than the Arduino IDE, this is set to a + meaningless version number. +- `{ide_version}`: Compatibility alias for `{runtime.ide.version}` +- `{runtime.os}`: the running OS ("linux", "windows", "macosx") + +Compatibility note: Versions before Arduino IDE 1.6.0 only used one digit per version number component in +`{runtime.ide.version}` (so 1.5.9 was `159`, not `10509`). ## platform.txt -The platform.txt file contains information about a platform's specific aspects (compilers -command line flags, paths, system libraries, etc.). +The platform.txt file contains information about a platform's specific aspects (compilers command line flags, paths, +system libraries, etc.). The following meta-data must be defined: name=Arduino AVR Boards version=1.5.3 -The **name** will be shown as the Arduino IDE's Board menu section title or the Name field of [`arduino-cli core list`](../commands/arduino-cli_core_list)'s output for the platform.
-The **version** is currently unused, it is reserved for future use (probably together with the Boards Manager to handle dependencies on cores). +The **name** will be shown as the Arduino IDE's Board menu section title or the Name field of +[`arduino-cli core list`](../commands/arduino-cli_core_list)'s output for the platform.
The **version** is currently +unused, it is reserved for future use (probably together with the Boards Manager to handle dependencies on cores). ### Build process -The platform.txt file is used to configure the build process. This is done through a list of **recipes**. Each recipe is a command line expression that explains how to call the compiler (or other tools) for every build step and which parameter should be passed. +The platform.txt file is used to configure the build process. This is done through a list of **recipes**. Each recipe is +a command line expression that explains how to call the compiler (or other tools) for every build step and which +parameter should be passed. -The Arduino development software, before starting the build, determines the list of files to compile. The list is composed of: +The Arduino development software, before starting the build, determines the list of files to compile. The list is +composed of: - the user's Sketch - source code in the selected board's Core - source code in the Libraries used in the sketch -A temporary folder is created to store the build artifacts whose path is available through the global property **{build.path}**. A property **{build.project_name}** with the name of the project and a property **{build.arch}** with the name of the architecture is set as well. +A temporary folder is created to store the build artifacts whose path is available through the global property +**{build.path}**. A property **{build.project_name}** with the name of the project and a property **{build.arch}** with +the name of the architecture is set as well. -* `{build.path}`: The path to the temporary folder to store build artifacts -* `{build.project_name}`: The project name -* `{build.arch}`: The MCU architecture (avr, sam, etc...) +- `{build.path}`: The path to the temporary folder to store build artifacts +- `{build.project_name}`: The project name +- `{build.arch}`: The MCU architecture (avr, sam, etc...) There are some other **{build.xxx}** properties available, that are explained in the boards.txt section of this guide. #### Recipes to compile source code -We said that the Arduino development software determines a list of files to compile. Each file can be source code written in C (.c files), C++ (.cpp files) or Assembly (.S files). Every language is compiled using its respective **recipe**: +We said that the Arduino development software determines a list of files to compile. Each file can be source code +written in C (.c files), C++ (.cpp files) or Assembly (.S files). Every language is compiled using its respective +**recipe**: -* `recipe.c.o.pattern`: for C files -* `recipe.cpp.o.pattern`: for CPP files -* `recipe.S.o.pattern`: for Assembly files +- `recipe.c.o.pattern`: for C files +- `recipe.cpp.o.pattern`: for CPP files +- `recipe.S.o.pattern`: for Assembly files The recipes can be built concatenating the following automatically generated properties (for each file compiled): -* `{includes}`: the list of include paths in the format "-I/include/path -I/another/path...." -* `{source_file}`: the path to the source file -* `{object_file}`: the path to the output file +- `{includes}`: the list of include paths in the format "-I/include/path -I/another/path...." +- `{source_file}`: the path to the source file +- `{object_file}`: the path to the output file For example the following is used for AVR: @@ -126,17 +153,20 @@ For example the following is used for AVR: ## Compile c files recipe.c.o.pattern="{compiler.path}{compiler.c.cmd}" {compiler.c.flags} -mmcu={build.mcu} -DF_CPU={build.f_cpu} -DARDUINO={runtime.ide.version} -DARDUINO_{build.board} -DARDUINO_ARCH_{build.arch} {build.extra_flags} {includes} "{source_file}" -o "{object_file}" -Note that some properties, like **{build.mcu}** for example, are taken from the **boards.txt** file which is documented later in this specification. +Note that some properties, like **{build.mcu}** for example, are taken from the **boards.txt** file which is documented +later in this specification. #### Recipes to build the core.a archive file -The core of the selected board is compiled as described in the previous paragraph, but the object files obtained from the compile are also archived into a static library named *core.a* using the **recipe.ar.pattern**. +The core of the selected board is compiled as described in the previous paragraph, but the object files obtained from +the compile are also archived into a static library named _core.a_ using the **recipe.ar.pattern**. The recipe can be built concatenating the following automatically generated properties: -* `{object_file}`: the object file to include in the archive -* `{archive_file_path}`: fully qualified archive file (ex. "/path/to/core.a"). This property was added in Arduino IDE 1.6.6/arduino builder 1.0.0-beta12 as a replacement for `{build.path}/{archive_file}`. -* `{archive_file}`: the name of the resulting archive (ex. "core.a") +- `{object_file}`: the object file to include in the archive +- `{archive_file_path}`: fully qualified archive file (ex. "/path/to/core.a"). This property was added in Arduino IDE + 1.6.6/arduino builder 1.0.0-beta12 as a replacement for `{build.path}/{archive_file}`. +- `{archive_file}`: the name of the resulting archive (ex. "core.a") For example, Arduino provides the following for AVR: @@ -150,13 +180,15 @@ For example, Arduino provides the following for AVR: #### Recipes for linking -All the artifacts produced by the previous steps (sketch object files, libraries object files and core.a archive) are linked together using the **recipe.c.combine.pattern**. +All the artifacts produced by the previous steps (sketch object files, libraries object files and core.a archive) are +linked together using the **recipe.c.combine.pattern**. The recipe can be built concatenating the following automatically generated properties: -* `{object_files}`: the list of object files to include in the archive ("file1.o file2.o ....") -* `{archive_file_path}`: fully qualified archive file (ex. "/path/to/core.a"). This property was added in Arduino IDE 1.6.6/arduino builder 1.0.0-beta12 as a replacement for `{build.path}/{archive_file}`. -* `{archive_file}`: the name of the core archive file (ex. "core.a") +- `{object_files}`: the list of object files to include in the archive ("file1.o file2.o ....") +- `{archive_file_path}`: fully qualified archive file (ex. "/path/to/core.a"). This property was added in Arduino IDE + 1.6.6/arduino builder 1.0.0-beta12 as a replacement for `{build.path}/{archive_file}`. +- `{archive_file}`: the name of the core archive file (ex. "core.a") For example the following is used for AVR: @@ -170,20 +202,21 @@ For example the following is used for AVR: #### Recipes for extraction of executable files and other binary data -An arbitrary number of extra steps can be performed at the end of objects linking. -These steps can be used to extract binary data used for upload and they are defined by a set of recipes with the following format: +An arbitrary number of extra steps can be performed at the end of objects linking. These steps can be used to extract +binary data used for upload and they are defined by a set of recipes with the following format: recipe.objcopy.FILE_EXTENSION_1.pattern=[.....] recipe.objcopy.FILE_EXTENSION_2.pattern=[.....] [.....] -`FILE_EXTENSION_x` must be replaced with the extension of the extracted file, for example the AVR platform needs two files a `.hex` and a `.eep`, so we made two recipes like: +`FILE_EXTENSION_x` must be replaced with the extension of the extracted file, for example the AVR platform needs two +files a `.hex` and a `.eep`, so we made two recipes like: recipe.objcopy.eep.pattern=[.....] recipe.objcopy.hex.pattern=[.....] -There are no specific properties set by the Arduino development software here. -A full example for the AVR platform can be: +There are no specific properties set by the Arduino development software here. A full example for the AVR platform can +be: ## Create eeprom recipe.objcopy.eep.pattern="{compiler.path}{compiler.objcopy.cmd}" {compiler.objcopy.eep.flags} "{build.path}/{build.project_name}.elf" "{build.path}/{build.project_name}.eep" @@ -193,10 +226,12 @@ A full example for the AVR platform can be: #### Recipes to compute binary sketch size -At the end of the build the Arduino development software shows the final binary sketch size to the user. The size is calculated using the recipe **recipe.size.pattern**. The output of the command executed using the recipe is parsed through the regular expressions set in the properties: +At the end of the build the Arduino development software shows the final binary sketch size to the user. The size is +calculated using the recipe **recipe.size.pattern**. The output of the command executed using the recipe is parsed +through the regular expressions set in the properties: -* **recipe.size.regex**: Program storage space used. -* **recipe.size.regex.data**: Dynamic memory used by global variables. +- **recipe.size.regex**: Program storage space used. +- **recipe.size.regex.data**: Dynamic memory used by global variables. For AVR we have: @@ -209,55 +244,72 @@ For AVR we have: #### Recipes to export compiled binary -When you do a **Sketch > Export compiled Binary** in the Arduino IDE, the compiled binary is copied from the build folder to the sketch folder. Two binaries are copied; the standard binary, and a binary that has been merged with the bootloader file (identified by the `.with_bootloader` in the filename). +When you do a **Sketch > Export compiled Binary** in the Arduino IDE, the compiled binary is copied from the build +folder to the sketch folder. Two binaries are copied; the standard binary, and a binary that has been merged with the +bootloader file (identified by the `.with_bootloader` in the filename). Two recipes affect how **Export compiled Binary** works: -* **recipe.output.tmp_file**: Defines the binary's filename in the build folder. -* **recipe.output.save_file**: Defines the filename to use when copying the binary file to the sketch folder. +- **recipe.output.tmp_file**: Defines the binary's filename in the build folder. +- **recipe.output.save_file**: Defines the filename to use when copying the binary file to the sketch folder. As with other processes, there are pre and post build hooks for **Export compiled Binary**. -The **recipe.hooks.savehex.presavehex.NUMBER.pattern** and **recipe.hooks.savehex.postsavehex.NUMBER.pattern** hooks (but not **recipe.output.tmp_file** and **recipe.output.save_file**) can be built concatenating the following automatically generated properties: +The **recipe.hooks.savehex.presavehex.NUMBER.pattern** and **recipe.hooks.savehex.postsavehex.NUMBER.pattern** hooks +(but not **recipe.output.tmp_file** and **recipe.output.save_file**) can be built concatenating the following +automatically generated properties: {sketch_path} - the absolute path of the sketch folder #### Recipe to run the preprocessor -For detecting what libraries to include in the build, and for generating function prototypes, (just) the preprocessor is run. For this, the **recipe.preproc.macros** recipe exists. This recipe must run the preprocessor on a given source file, writing the preprocessed output to a given output file, and generate (only) preprocessor errors on standard output. This preprocessor run should happen with the same defines and other preprocessor-influencing-options as for normally compiling the source files. + +For detecting what libraries to include in the build, and for generating function prototypes, (just) the preprocessor is +run. For this, the **recipe.preproc.macros** recipe exists. This recipe must run the preprocessor on a given source +file, writing the preprocessed output to a given output file, and generate (only) preprocessor errors on standard +output. This preprocessor run should happen with the same defines and other preprocessor-influencing-options as for +normally compiling the source files. The recipes can be built concatenating other automatically generated properties (for each file compiled): -* `{includes}`: the list of include paths in the format "-I/include/path -I/another/path...." -* `{source_file}`: the path to the source file -* `{preprocessed_file_path}`: the path to the output file +- `{includes}`: the list of include paths in the format "-I/include/path -I/another/path...." +- `{source_file}`: the path to the source file +- `{preprocessed_file_path}`: the path to the output file For example the following is used for AVR: preproc.macros.flags=-w -x c++ -E -CC recipe.preproc.macros="{compiler.path}{compiler.cpp.cmd}" {compiler.cpp.flags} {preproc.macros.flags} -mmcu={build.mcu} -DF_CPU={build.f_cpu} -DARDUINO={runtime.ide.version} -DARDUINO_{build.board} -DARDUINO_ARCH_{build.arch} {compiler.cpp.extra_flags} {build.extra_flags} {includes} "{source_file}" -o "{preprocessed_file_path}" -Note that the `{preprocessed_file_path}` might point to (your operating system's equivalent) of `/dev/null`. In this case, also passing `-MMD` to gcc is problematic, as it will try to generate a dependency file called `/dev/null.d`, which will usually result in a permission error. Since platforms typically include `{compiler.cpp.flags}` here, which includes `-MMD`, the `-MMD` option is automatically filtered out of the `recipe.preproc.macros` recipe to prevent this error. +Note that the `{preprocessed_file_path}` might point to (your operating system's equivalent) of `/dev/null`. In this +case, also passing `-MMD` to gcc is problematic, as it will try to generate a dependency file called `/dev/null.d`, +which will usually result in a permission error. Since platforms typically include `{compiler.cpp.flags}` here, which +includes `-MMD`, the `-MMD` option is automatically filtered out of the `recipe.preproc.macros` recipe to prevent this +error. -Note that older Arduino IDE versions used the **recipe.preproc.includes** recipe to determine includes, which is undocumented here. Since Arduino IDE 1.6.7 (arduino-builder 1.2.0) this was changed and **recipe.preproc.includes** is no longer used. +Note that older Arduino IDE versions used the **recipe.preproc.includes** recipe to determine includes, which is +undocumented here. Since Arduino IDE 1.6.7 (arduino-builder 1.2.0) this was changed and **recipe.preproc.includes** is +no longer used. #### Pre and post build hooks (since Arduino IDE 1.6.5) -You can specify pre and post actions around each recipe. These are called "hooks". Here is the complete list of available hooks: - -* `recipe.hooks.sketch.prebuild.NUMBER.pattern` (called before sketch compilation) -* `recipe.hooks.sketch.postbuild.NUMBER.pattern` (called after sketch compilation) -* `recipe.hooks.libraries.prebuild.NUMBER.pattern` (called before libraries compilation) -* `recipe.hooks.libraries.postbuild.NUMBER.pattern` (called after libraries compilation) -* `recipe.hooks.core.prebuild.NUMBER.pattern` (called before core compilation) -* `recipe.hooks.core.postbuild.NUMBER.pattern` (called after core compilation) -* `recipe.hooks.linking.prelink.NUMBER.pattern` (called before linking) -* `recipe.hooks.linking.postlink.NUMBER.pattern` (called after linking) -* `recipe.hooks.objcopy.preobjcopy.NUMBER.pattern` (called before objcopy recipes execution) -* `recipe.hooks.objcopy.postobjcopy.NUMBER.pattern` (called after objcopy recipes execution) -* `recipe.hooks.savehex.presavehex.NUMBER.pattern` (called before savehex recipe execution) -* `recipe.hooks.savehex.postsavehex.NUMBER.pattern` (called after savehex recipe execution) +You can specify pre and post actions around each recipe. These are called "hooks". Here is the complete list of +available hooks: + +- `recipe.hooks.sketch.prebuild.NUMBER.pattern` (called before sketch compilation) +- `recipe.hooks.sketch.postbuild.NUMBER.pattern` (called after sketch compilation) +- `recipe.hooks.libraries.prebuild.NUMBER.pattern` (called before libraries compilation) +- `recipe.hooks.libraries.postbuild.NUMBER.pattern` (called after libraries compilation) +- `recipe.hooks.core.prebuild.NUMBER.pattern` (called before core compilation) +- `recipe.hooks.core.postbuild.NUMBER.pattern` (called after core compilation) +- `recipe.hooks.linking.prelink.NUMBER.pattern` (called before linking) +- `recipe.hooks.linking.postlink.NUMBER.pattern` (called after linking) +- `recipe.hooks.objcopy.preobjcopy.NUMBER.pattern` (called before objcopy recipes execution) +- `recipe.hooks.objcopy.postobjcopy.NUMBER.pattern` (called after objcopy recipes execution) +- `recipe.hooks.savehex.presavehex.NUMBER.pattern` (called before savehex recipe execution) +- `recipe.hooks.savehex.postsavehex.NUMBER.pattern` (called after savehex recipe execution) Example: you want to execute 2 commands before sketch compilation and 1 after linking. You'll add to your platform.txt + ``` recipe.hooks.sketch.prebuild.1.pattern=echo sketch compilation started at recipe.hooks.sketch.prebuild.2.pattern=date @@ -265,7 +317,9 @@ recipe.hooks.sketch.prebuild.2.pattern=date recipe.hooks.linking.postlink.1.pattern=echo linking is complete ``` -Warning: hooks recipes are sorted before execution. If you need to write more than 10 recipes for a single hook, pad the number with a zero, for example: +Warning: hooks recipes are sorted before execution. If you need to write more than 10 recipes for a single hook, pad the +number with a zero, for example: + ``` recipe.hooks.sketch.prebuild.01.pattern=echo 1 recipe.hooks.sketch.prebuild.02.pattern=echo 2 @@ -275,19 +329,24 @@ recipe.hooks.sketch.prebuild.11.pattern=echo 11 ## Global platform.txt -Properties defined in a platform.txt created in the **hardware** subfolder of the Arduino IDE installation folder will be used for all platforms and will override local properties. This feature is currently only available when using the Arduino IDE. +Properties defined in a platform.txt created in the **hardware** subfolder of the Arduino IDE installation folder will +be used for all platforms and will override local properties. This feature is currently only available when using the +Arduino IDE. ## platform.local.txt -Introduced in Arduino IDE 1.5.7. This file can be used to override properties defined in platform.txt or define new properties without modifying platform.txt (e.g. when platform.txt is tracked by a version control system). It should be placed in the same folder as the platform.txt it supplements. - +Introduced in Arduino IDE 1.5.7. This file can be used to override properties defined in platform.txt or define new +properties without modifying platform.txt (e.g. when platform.txt is tracked by a version control system). It should be +placed in the same folder as the platform.txt it supplements. ## boards.txt -This file contains definitions and meta-data for the boards supported. Every board must be referred through its short name, the board ID. The settings for a board are defined through a set of properties -with keys having the board ID as prefix. +This file contains definitions and meta-data for the boards supported. Every board must be referred through its short +name, the board ID. The settings for a board are defined through a set of properties with keys having the board ID as +prefix. -For example the board ID chosen for the Arduino Uno board is "uno". An extract of the Uno board configuration in boards.txt looks like: +For example the board ID chosen for the Arduino Uno board is "uno". An extract of the Uno board configuration in +boards.txt looks like: [......] uno.name=Arduino Uno @@ -300,11 +359,15 @@ For example the board ID chosen for the Arduino Uno board is "uno". An extract o Note that all the relevant keys start with the board ID **uno.xxxxx**. -The **uno.name** property contains the human-friendly name of the board. This is shown in the Board menu of the IDEs, the "Board Name" field of Arduino CLI's text output, or the "name" key of Arduino CLI's JSON output. +The **uno.name** property contains the human-friendly name of the board. This is shown in the Board menu of the IDEs, +the "Board Name" field of Arduino CLI's text output, or the "name" key of Arduino CLI's JSON output. -The **uno.build.board** property is used to set a compile-time variable **ARDUINO_{build.board}** to allow use of conditional code between `#ifdef`s. A **build.board** value is automatically generated if not defined. In this case the variable defined at compile time will be `ARDUINO_AVR_UNO`. +The **uno.build.board** property is used to set a compile-time variable **ARDUINO\_{build.board}** to allow use of +conditional code between `#ifdef`s. A **build.board** value is automatically generated if not defined. In this case the +variable defined at compile time will be `ARDUINO_AVR_UNO`. -The other properties will override the corresponding global properties when the user selects the board. These properties will be globally available, in other configuration files too, without the board ID prefix: +The other properties will override the corresponding global properties when the user selects the board. These properties +will be globally available, in other configuration files too, without the board ID prefix: uno.build.mcu => build.mcu uno.build.f_cpu => build.f_cpu @@ -312,22 +375,28 @@ The other properties will override the corresponding global properties when the uno.build.core => build.core uno.build.variant => build.variant -This explains the presence of **{build.mcu}** or **{build.board}** in the platform.txt recipes: their value is overwritten respectively by **{uno.build.mcu}** and **{uno.build.board}** when the Uno board is selected! -Moreover the following properties are automatically generated: +This explains the presence of **{build.mcu}** or **{build.board}** in the platform.txt recipes: their value is +overwritten respectively by **{uno.build.mcu}** and **{uno.build.board}** when the Uno board is selected! Moreover the +following properties are automatically generated: -* `{build.core.path}`: The path to the selected board's core folder (inside the [core platform](#platform-terminology), for example hardware/arduino/avr/core/arduino) -* `{build.system.path}`: The path to the [core platform](#platform-terminology)'s system folder if available (for example hardware/arduino/sam/system) -* `{build.variant.path}`: The path to the selected board variant folder (inside the [variant platform](#platform-terminology), for example hardware/arduino/avr/variants/micro) +- `{build.core.path}`: The path to the selected board's core folder (inside the [core platform](#platform-terminology), + for example hardware/arduino/avr/core/arduino) +- `{build.system.path}`: The path to the [core platform](#platform-terminology)'s system folder if available (for + example hardware/arduino/sam/system) +- `{build.variant.path}`: The path to the selected board variant folder (inside the + [variant platform](#platform-terminology), for example hardware/arduino/avr/variants/micro) ### Cores -Cores are placed inside the **cores** subfolder. Many different cores can be provided within a single platform. For example the following could be a valid platform layout: +Cores are placed inside the **cores** subfolder. Many different cores can be provided within a single platform. For +example the following could be a valid platform layout: -* `hardware/arduino/avr/cores/`: Cores folder for "avr" architecture, package "arduino" -* `hardware/arduino/avr/cores/arduino`: the Arduino Core -* `hardware/arduino/avr/cores/rtos`: an hypothetical RTOS Core +- `hardware/arduino/avr/cores/`: Cores folder for "avr" architecture, package "arduino" +- `hardware/arduino/avr/cores/arduino`: the Arduino Core +- `hardware/arduino/avr/cores/rtos`: an hypothetical RTOS Core -The board's property **build.core** is used to find the core that must be compiled and linked when the board is selected. For example if a board needs the Arduino core the **build.core** variable should be set to: +The board's property **build.core** is used to find the core that must be compiled and linked when the board is +selected. For example if a board needs the Arduino core the **build.core** variable should be set to: uno.build.core=arduino @@ -335,37 +404,42 @@ or if the RTOS core is needed, to: uno.build.core=rtos -In any case the contents of the selected core folder are compiled and the core folder path is added to the include files search path. +In any case the contents of the selected core folder are compiled and the core folder path is added to the include files +search path. ### Core Variants -Sometimes a board needs some tweaking on default core configuration (different pin mapping is a typical example). A core variant folder is an additional folder that is compiled together with the core and allows to easily add specific configurations. +Sometimes a board needs some tweaking on default core configuration (different pin mapping is a typical example). A core +variant folder is an additional folder that is compiled together with the core and allows to easily add specific +configurations. -Variants must be placed inside the **variants** folder in the current architecture. -For example, Arduino AVR Boards uses: +Variants must be placed inside the **variants** folder in the current architecture. For example, Arduino AVR Boards +uses: -* `hardware/arduino/avr/cores`: Core folder for "avr" architecture, "arduino" package -* `hardware/arduino/avr/cores/arduino`: The Arduino core -* `hardware/arduino/avr/variants/`: Variant folder for "avr" architecture, "arduino" package -* `hardware/arduino/avr/variants/standard`: ATmega328 based variants -* `hardware/arduino/avr/variants/leonardo`: ATmega32U4 based variants +- `hardware/arduino/avr/cores`: Core folder for "avr" architecture, "arduino" package +- `hardware/arduino/avr/cores/arduino`: The Arduino core +- `hardware/arduino/avr/variants/`: Variant folder for "avr" architecture, "arduino" package +- `hardware/arduino/avr/variants/standard`: ATmega328 based variants +- `hardware/arduino/avr/variants/leonardo`: ATmega32U4 based variants -In this example, the Arduino Uno board needs the *standard* variant so the **build.variant** property is set to *standard*: +In this example, the Arduino Uno board needs the _standard_ variant so the **build.variant** property is set to +_standard_: [.....] uno.build.core=arduino uno.build.variant=standard [.....] -instead, the Arduino Leonardo board needs the *leonardo* variant: +instead, the Arduino Leonardo board needs the _leonardo_ variant: [.....] leonardo.build.core=arduino leonardo.build.variant=leonardo [.....] -In the example above, both Uno and Leonardo share the same core but use different variants.
-In any case, the contents of the selected variant folder path is added to the include search path and its contents are compiled and linked with the sketch. +In the example above, both Uno and Leonardo share the same core but use different variants.
In any case, the +contents of the selected variant folder path is added to the include search path and its contents are compiled and +linked with the sketch. The parameter **build.variant.path** is automatically generated. @@ -379,17 +453,21 @@ The value of the property is ignored; it's the presence or absence of the proper ## Tools -The Arduino development software uses external command line tools to upload the compiled sketch to the board or to burn bootloaders using external programmers. For example, *avrdude* is used for AVR based boards and *bossac* for SAM based boards, but there is no limit, any command line executable can be used. The command line parameters are specified using **recipes** in the same way used for platform build process. +The Arduino development software uses external command line tools to upload the compiled sketch to the board or to burn +bootloaders using external programmers. For example, _avrdude_ is used for AVR based boards and _bossac_ for SAM based +boards, but there is no limit, any command line executable can be used. The command line parameters are specified using +**recipes** in the same way used for platform build process. -Tools are configured inside the platform.txt file. Every Tool is identified by a short name, the Tool ID. -A tool can be used for different purposes: +Tools are configured inside the platform.txt file. Every Tool is identified by a short name, the Tool ID. A tool can be +used for different purposes: - **upload** a sketch to the target board (using a bootloader preinstalled on the board) - **program** a sketch to the target board using an external programmer - **erase** the target board's flash memory using an external programmer - burn a **bootloader** into the target board using an external programmer -Each action has its own recipe and its configuration is done through a set of properties having key starting with **tools** prefix followed by the tool ID and the action: +Each action has its own recipe and its configuration is done through a set of properties having key starting with +**tools** prefix followed by the tool ID and the action: [....] tools.avrdude.upload.pattern=[......] @@ -401,8 +479,8 @@ Each action has its own recipe and its configuration is done through a set of pr tools.avrdude.bootloader.pattern=[......] [.....] -A tool may have some actions not defined (it's not mandatory to define all four actions).
-Let's look at how the **upload** action is defined for avrdude: +A tool may have some actions not defined (it's not mandatory to define all four actions).
Let's look at how the +**upload** action is defined for avrdude: tools.avrdude.path={runtime.tools.avrdude.path} tools.avrdude.cmd.path={path}/bin/avrdude @@ -410,14 +488,21 @@ Let's look at how the **upload** action is defined for avrdude: tools.avrdude.upload.pattern="{cmd.path}" "-C{config.path}" -p{build.mcu} -c{upload.protocol} -P{serial.port} -b{upload.speed} -D "-Uflash:w:{build.path}/{build.project_name}.hex:i" -A **{runtime.tools.TOOL_NAME.path}** and **{runtime.tools.TOOL_NAME-TOOL_VERSION.path}** property is generated for the tools of Arduino AVR Boards and any other platform installed via Boards Manager. **{runtime.tools.TOOL_NAME.path}** points to the latest version of the tool available. +A **{runtime.tools.TOOL_NAME.path}** and **{runtime.tools.TOOL_NAME-TOOL_VERSION.path}** property is generated for the +tools of Arduino AVR Boards and any other platform installed via Boards Manager. **{runtime.tools.TOOL_NAME.path}** +points to the latest version of the tool available. -The tool configuration properties are available globally without the prefix. For example, the **tools.avrdude.cmd.path** property can be used as **{cmd.path}** inside the recipe, and the same happens for all the other avrdude configuration variables. +The tool configuration properties are available globally without the prefix. For example, the **tools.avrdude.cmd.path** +property can be used as **{cmd.path}** inside the recipe, and the same happens for all the other avrdude configuration +variables. #### Verbose parameter -It is possible for the user to enable verbosity from the Preferences panel of the IDEs or Arduino CLI's `--verbose` flag. This preference is transferred to the command line using the **ACTION.verbose** property (where ACTION is the action we are considering).
-When the verbose mode is enabled the **tools.TOOL_ID.ACTION.params.verbose** property is copied into **ACTION.verbose**. When the verbose mode is disabled, the **tools.TOOL_ID.ACTION.params.quiet** property is copied into **ACTION.verbose**. Confused? Maybe an example will clear things: +It is possible for the user to enable verbosity from the Preferences panel of the IDEs or Arduino CLI's `--verbose` +flag. This preference is transferred to the command line using the **ACTION.verbose** property (where ACTION is the +action we are considering).
When the verbose mode is enabled the **tools.TOOL_ID.ACTION.params.verbose** property is +copied into **ACTION.verbose**. When the verbose mode is disabled, the **tools.TOOL_ID.ACTION.params.quiet** property is +copied into **ACTION.verbose**. Confused? Maybe an example will clear things: tools.avrdude.upload.params.verbose=-v -v -v -v tools.avrdude.upload.params.quiet=-q -q @@ -433,10 +518,10 @@ If the user didn't enable verbose mode, then **{upload.params.quiet}** is used i ### Sketch upload configuration -The Upload action is triggered when the user clicks on the "Upload" button on the IDE toolbar or uses [`arduino-cli upload`](../commands/arduino-cli_upload). -Arduino uses the term "upload" for the process of transferring a program to the Arduino board. -The **upload.tool** property determines the tool to be used for upload. -A specific **upload.tool** property should be defined for every board in boards.txt: +The Upload action is triggered when the user clicks on the "Upload" button on the IDE toolbar or uses +[`arduino-cli upload`](../commands/arduino-cli_upload). Arduino uses the term "upload" for the process of transferring a +program to the Arduino board. The **upload.tool** property determines the tool to be used for upload. A specific +**upload.tool** property should be defined for every board in boards.txt: [......] uno.upload.tool=avrdude @@ -469,38 +554,59 @@ Most **{upload.XXXX}** variables are used later in the avrdude upload recipe in [.....] #### 1200 bps bootloader reset -Some Arduino boards use a dedicated USB-to-serial chip, that takes care of restarting the main MCU (starting the bootloader) when the serial port is opened. However, boards that have a native USB connection (such as the Leonardo or Zero) will have to disconnect from USB when rebooting into the bootloader (after which the bootloader reconnects to USB and offers a new serial port for uploading). After the upload is complete, the bootloader disconnects from USB again, starts the sketch, which then reconnects to USB. Because of these reconnections, the standard restart-on-serial open will not work, since that would cause the serial port to disappear and be closed again. Instead, the sketch running on these boards interprets a bitrate of 1200 bps as a signal the bootloader should be started. + +Some Arduino boards use a dedicated USB-to-serial chip, that takes care of restarting the main MCU (starting the +bootloader) when the serial port is opened. However, boards that have a native USB connection (such as the Leonardo or +Zero) will have to disconnect from USB when rebooting into the bootloader (after which the bootloader reconnects to USB +and offers a new serial port for uploading). After the upload is complete, the bootloader disconnects from USB again, +starts the sketch, which then reconnects to USB. Because of these reconnections, the standard restart-on-serial open +will not work, since that would cause the serial port to disappear and be closed again. Instead, the sketch running on +these boards interprets a bitrate of 1200 bps as a signal the bootloader should be started. To let the Arduino development software perform these steps, two board parameters can be set: -* `use_1200bps_touch` causes the selected serial port to be briefly opened at 1200 bps (8N1) before starting the upload. -* `wait_for_upload_port` causes the upload procedure to wait for the serial port to (re)appear before and after the upload. This is only used when `use_1200bps_touch` is also set. When set, after doing the 1200 bps touch, the development software will wait for a new serial port to appear and use that as the port for uploads. Alternatively, if the original port does not disappear within a few seconds, the upload continues with the original port (which can be the case if the board was already put into bootloader manually, or the the disconnect and reconnect was missed). Additionally, after the upload is complete, the IDE again waits for a new port to appear (or the originally selected port to be present). +- `use_1200bps_touch` causes the selected serial port to be briefly opened at 1200 bps (8N1) before starting the upload. +- `wait_for_upload_port` causes the upload procedure to wait for the serial port to (re)appear before and after the + upload. This is only used when `use_1200bps_touch` is also set. When set, after doing the 1200 bps touch, the + development software will wait for a new serial port to appear and use that as the port for uploads. Alternatively, if + the original port does not disappear within a few seconds, the upload continues with the original port (which can be + the case if the board was already put into bootloader manually, or the the disconnect and reconnect was missed). + Additionally, after the upload is complete, the IDE again waits for a new port to appear (or the originally selected + port to be present). -Note that the IDE implementation of this 1200 bps touch has some peculiarities, and the newer `arduino-cli` implementation also seems different (does not wait for the port after the reset, which is probably only needed in the IDE to prevent opening the wrong port on the serial monitor, and does not have a shorter timeout when the port never disappears). +Note that the IDE implementation of this 1200 bps touch has some peculiarities, and the newer `arduino-cli` +implementation also seems different (does not wait for the port after the reset, which is probably only needed in the +IDE to prevent opening the wrong port on the serial monitor, and does not have a shorter timeout when the port never +disappears). #### Upload Using Programmer by default -If the **upload.protocol** property is not defined for a board, the Arduino IDE's "Upload" process will use the same behavior as ["Upload Using Programmer"](#upload-using-an-external-programmer). This is convenient for boards which only support uploading via programmer. +If the **upload.protocol** property is not defined for a board, the Arduino IDE's "Upload" process will use the same +behavior as ["Upload Using Programmer"](#upload-using-an-external-programmer). This is convenient for boards which only +support uploading via programmer. ### Serial port -The full path (e.g., `/dev/ttyACM0`) of the port selected via the IDE or [`arduino-cli upload`](../commands/arduino-cli_upload)'s `--port` option is available as a configuration property **{serial.port}**. +The full path (e.g., `/dev/ttyACM0`) of the port selected via the IDE or +[`arduino-cli upload`](../commands/arduino-cli_upload)'s `--port` option is available as a configuration property +**{serial.port}**. -The file component of the port's path (e.g., `ttyACM0`) is available as the configuration property **{serial.port.file}**. +The file component of the port's path (e.g., `ttyACM0`) is available as the configuration property +**{serial.port.file}**. ### Upload using an external programmer -**TODO...**
-The platform.txt associated with the selected programmer will be used. +**TODO...**
The platform.txt associated with the selected programmer will be used. ### Burn Bootloader -**TODO...**
-The platform.txt associated with the selected board will be used. +**TODO...**
The platform.txt associated with the selected board will be used. ## Custom board options -It can sometimes be useful to provide user selectable configuration options for a specific board. For example, a board could be provided in two or more variants with different CPUs, or may have different crystal speed based on the board model, and so on... +It can sometimes be useful to provide user selectable configuration options for a specific board. For example, a board +could be provided in two or more variants with different CPUs, or may have different crystal speed based on the board +model, and so on... When using Arduino CLI, the option can be selected via the FQBN. @@ -508,18 +614,19 @@ In the Arduino IDE the options add extra menu items under the "Tools" menu. In Arduino Web Editor, the options are displayed in the "Flavours" menu. -Let's see an example of how a custom option is implemented. -The board used in the example is the Arduino Duemilanove. This board was produced in two models, one with an ATmega168 CPU and another with an ATmega328P.
-We are going then to define a custom option, using the "cpu" MENU_ID, that allows the user to choose between the two -different microcontrollers. +Let's see an example of how a custom option is implemented. The board used in the example is the Arduino Duemilanove. +This board was produced in two models, one with an ATmega168 CPU and another with an ATmega328P.
We are going then +to define a custom option, using the "cpu" MENU_ID, that allows the user to choose between the two different +microcontrollers. -We must first define a set of **menu.MENU_ID=Text** properties. Text is what is displayed on the GUI for every custom menu we are going to create and must be declared at the beginning of the boards.txt file: +We must first define a set of **menu.MENU_ID=Text** properties. Text is what is displayed on the GUI for every custom +menu we are going to create and must be declared at the beginning of the boards.txt file: menu.cpu=Processor [.....] -in this case, the menu name is "Processor".
-Now let's add, always in the boards.txt file, the default configuration (common to all processors) for the duemilanove board: +in this case, the menu name is "Processor".
Now let's add, always in the boards.txt file, the default configuration +(common to all processors) for the duemilanove board: menu.cpu=Processor [.....] @@ -540,9 +647,9 @@ Now let's define the possible values of the "cpu" option: duemilanove.menu.cpu.atmega168=ATmega168 [.....] -We have defined two values: "atmega328" and "atmega168".
-Note that the property keys must follow the format **BOARD_ID.menu.MENU_ID.OPTION_ID=Text**, where Text is what is displayed under the "Processor" menu in the IDE's GUI.
-Finally, the specific configuration for each option value: +We have defined two values: "atmega328" and "atmega168".
Note that the property keys must follow the format +**BOARD_ID.menu.MENU_ID.OPTION_ID=Text**, where Text is what is displayed under the "Processor" menu in the IDE's +GUI.
Finally, the specific configuration for each option value: [.....] ## Arduino Duemilanove w/ ATmega328P @@ -558,7 +665,9 @@ Finally, the specific configuration for each option value: duemilanove.menu.cpu.atmega168.build.mcu=atmega168 [.....] -Note that when the user selects an option value, all the "sub properties" of that value are copied in the global configuration. For example when the user selects "ATmega168" from the "Processor" menu, or uses the FQBN `arduino:avr:duemilanove:cpu=atmega168` with Arduino CLI, the configuration under atmega168 is made available globally: +Note that when the user selects an option value, all the "sub properties" of that value are copied in the global +configuration. For example when the user selects "ATmega168" from the "Processor" menu, or uses the FQBN +`arduino:avr:duemilanove:cpu=atmega168` with Arduino CLI, the configuration under atmega168 is made available globally: duemilanove.menu.cpu.atmega168.upload.maximum_size => upload.maximum_size duemilanove.menu.cpu.atmega168.upload.speed => upload.speed @@ -568,18 +677,24 @@ There is no limit to the number of custom menus that can be defined. ## Referencing another core, variant or tool -Inside the boards.txt we can define a board that uses a core provided by another vendor/maintainer using the syntax **VENDOR_ID:CORE_ID**. For example, if we want to define a board that uses the "arduino" core from the "arduino" vendor we should write: +Inside the boards.txt we can define a board that uses a core provided by another vendor/maintainer using the syntax +**VENDOR_ID:CORE_ID**. For example, if we want to define a board that uses the "arduino" core from the "arduino" vendor +we should write: [....] myboard.name=My Wonderful Arduino Compatible board myboard.build.core=arduino:arduino [....] -Note that we don't need to specify any architecture since the same architecture of "myboard" is used, so we just say "arduino:arduino" instead of "arduino:avr:arduino". +Note that we don't need to specify any architecture since the same architecture of "myboard" is used, so we just say +"arduino:arduino" instead of "arduino:avr:arduino". -The platform.txt settings are inherited from the referenced core platform, thus there is no need to provide a platform.txt unless there are some specific properties that need to be overridden. +The platform.txt settings are inherited from the referenced core platform, thus there is no need to provide a +platform.txt unless there are some specific properties that need to be overridden. -The libraries from the referenced platform are used, thus there is no need to provide those libraries. If libraries are provided the list of available libraries are the sum of the 2 libraries where the referencing platform has priority over the referenced platform. +The libraries from the referenced platform are used, thus there is no need to provide those libraries. If libraries are +provided the list of available libraries are the sum of the 2 libraries where the referencing platform has priority over +the referenced platform. In the same way we can use variants and tools defined on another platform: @@ -589,27 +704,36 @@ In the same way we can use variants and tools defined on another platform: myboard.bootloader.tool=arduino:avrdude [....] -Using this syntax allows us to reduce the minimum set of files needed to define a new "hardware" to just the boards.txt file. +Using this syntax allows us to reduce the minimum set of files needed to define a new "hardware" to just the boards.txt +file. -Note that referencing a variant in another platform does *not* inherit any properties from that platform's platform.txt (like referencing a core does). +Note that referencing a variant in another platform does _not_ inherit any properties from that platform's platform.txt +(like referencing a core does). ### Platform Terminology -Because boards can reference cores, variants and tools in different platforms, this means that a single build or upload can use data from up to four different platforms. To keep this clear, the following terminology is used: -* The "board platform" is the platform that defines the currently selected board (e.g. the platform that contains the board.txt the board is defined in. -* The "core platform" is the the platform that contains the core to be used. -* The "variant platform" is the platform that contains the variant to be used. -* The "tool platform" is the platform that contains the tool used for the current operation. +Because boards can reference cores, variants and tools in different platforms, this means that a single build or upload +can use data from up to four different platforms. To keep this clear, the following terminology is used: + +- The "board platform" is the platform that defines the currently selected board (e.g. the platform that contains the + board.txt the board is defined in. +- The "core platform" is the the platform that contains the core to be used. +- The "variant platform" is the platform that contains the variant to be used. +- The "tool platform" is the platform that contains the tool used for the current operation. In the most common case, without any references, all of these will refer to the same platform. -Note that the above terminology is not in widespread use, but was invented for clarity within this document. In the actual arduino-cli code, the "board platform" is called `targetPlatform`, the "core platform" is called `actualPlatform`, the others are pretty much nameless. +Note that the above terminology is not in widespread use, but was invented for clarity within this document. In the +actual arduino-cli code, the "board platform" is called `targetPlatform`, the "core platform" is called +`actualPlatform`, the others are pretty much nameless. ## boards.local.txt -Introduced in Arduino IDE 1.6.6. This file can be used to override properties defined in boards.txt or define new properties without modifying boards.txt. - +Introduced in Arduino IDE 1.6.6. This file can be used to override properties defined in boards.txt or define new +properties without modifying boards.txt. ## keywords.txt -As of Arduino IDE 1.6.6, per-platform keywords can be defined by adding a keywords.txt file to the platform's architecture folder. These keywords are only highlighted in the Arduino IDE when one of the boards of that platform are selected. This file follows the [same format](library-specification.md#keywords) as the keywords.txt used in libraries. +As of Arduino IDE 1.6.6, per-platform keywords can be defined by adding a keywords.txt file to the platform's +architecture folder. These keywords are only highlighted in the Arduino IDE when one of the boards of that platform are +selected. This file follows the [same format](library-specification.md#keywords) as the keywords.txt used in libraries. diff --git a/docs/sketch-build-process.md b/docs/sketch-build-process.md index 739150f04d1..5186d4ccb9e 100644 --- a/docs/sketch-build-process.md +++ b/docs/sketch-build-process.md @@ -1,19 +1,37 @@ -The process the Arduino development software uses to build a sketch. More useful information can be found in the [Arduino platform specification](platform-specification.md). Note that the following refers specifically to the build process for AVR targets. Other architectures will have a similar build process. +The process the Arduino development software uses to build a sketch. More useful information can be found in the +[Arduino platform specification](platform-specification.md). Note that the following refers specifically to the build +process for AVR targets. Other architectures will have a similar build process. ## Overview -A number of things have to happen for your Arduino code to get onto the Arduino board. First, the Arduino development software performs some minor pre-processing to turn your sketch into a C++ program. Next, dependencies of the sketch are located. It then gets passed to a compiler (avr-gcc), which turns the human readable code into machine readable instructions (or object files). Then your code gets combined with (linked against) the standard Arduino libraries that provide basic functions like `digitalWrite()` or `Serial.print()`. The result is a single Intel hex file, which contains the specific bytes that need to be written to the program memory of the chip on the Arduino board. This file is then uploaded to the board: transmitted over the USB or serial connection via the bootloader already on the chip or with external programming hardware. +A number of things have to happen for your Arduino code to get onto the Arduino board. First, the Arduino development +software performs some minor pre-processing to turn your sketch into a C++ program. Next, dependencies of the sketch are +located. It then gets passed to a compiler (avr-gcc), which turns the human readable code into machine readable +instructions (or object files). Then your code gets combined with (linked against) the standard Arduino libraries that +provide basic functions like `digitalWrite()` or `Serial.print()`. The result is a single Intel hex file, which contains +the specific bytes that need to be written to the program memory of the chip on the Arduino board. This file is then +uploaded to the board: transmitted over the USB or serial connection via the bootloader already on the chip or with +external programming hardware. ## Pre-Processing -The Arduino development software performs a few transformations to your sketch before passing it to the avr-gcc compiler: - -- All .ino and .pde files in the sketch folder (shown in the Arduino IDE as tabs with no extension) are concatenated together, starting with the file that matches the folder name followed by the others in alphabetical order, and the .cpp extension is added to the filename. -- If not already present, `#include ` is added to the sketch. This header file (found in the core folder for the currently selected board) includes all the definitions needed for the standard Arduino core. -- Prototypes are generated for all function definitions in .ino/.pde files that don't already have prototypes. In some rare cases prototype generation may fail for some functions. To work around this, you can provide your own prototypes for these functions. +The Arduino development software performs a few transformations to your sketch before passing it to the avr-gcc +compiler: + +- All .ino and .pde files in the sketch folder (shown in the Arduino IDE as tabs with no extension) are concatenated + together, starting with the file that matches the folder name followed by the others in alphabetical order, and the + .cpp extension is added to the filename. +- If not already present, `#include ` is added to the sketch. This header file (found in the core folder for + the currently selected board) includes all the definitions needed for the standard Arduino core. +- Prototypes are generated for all function definitions in .ino/.pde files that don't already have prototypes. In some + rare cases prototype generation may fail for some functions. To work around this, you can provide your own prototypes + for these functions. - `#line` directives are added to make warning or error messages reflect the original sketch layout. -No pre-processing is done to files in a sketch with any extension other than .ino or .pde. Additionally, .h files in the sketch are not automatically #included from the main sketch file. Further, if you want to call functions defined in a .c file from a .cpp file (like one generated from your sketch), you'll need to wrap its declarations in an `extern "C" {}` block that is defined only inside of C++ files. +No pre-processing is done to files in a sketch with any extension other than .ino or .pde. Additionally, .h files in the +sketch are not automatically #included from the main sketch file. Further, if you want to call functions defined in a .c +file from a .cpp file (like one generated from your sketch), you'll need to wrap its declarations in an `extern "C" {}` +block that is defined only inside of C++ files. ## Dependency Resolution @@ -24,81 +42,110 @@ The sketch is scanned recursively for dependencies. There are predefined include 1. Standard system directories (e.g., [`{runtime.tools.avr-gcc.path}/avr/include`](platform-specification.md#tools)) 1. Include search paths added to resolve prior dependencies -If the dependency is not present in any of those locations, the installed libraries are then searched (see the [**Location Priority** table](#location-priority) below for library locations). For information on the allowed library sub-folder structures see [the Arduino library specification](library-specification.md#source-code). `-I` options are generated for the path to each library dependency and appended to the [`includes` property](platform-specification.md#recipes-to-compile-source-code), to be used in [compilation recipes](platform-specification.md#recipes-to-compile-source-code) in platform.txt. +If the dependency is not present in any of those locations, the installed libraries are then searched (see the +[**Location Priority** table](#location-priority) below for library locations). For information on the allowed library +sub-folder structures see [the Arduino library specification](library-specification.md#source-code). `-I` options are +generated for the path to each library dependency and appended to the +[`includes` property](platform-specification.md#recipes-to-compile-source-code), to be used in +[compilation recipes](platform-specification.md#recipes-to-compile-source-code) in platform.txt. -If multiple libraries contain a file that matches the `#include` directive, the priority is determined by applying the following rules, one by one in this order, until a rule determines a winner: +If multiple libraries contain a file that matches the `#include` directive, the priority is determined by applying the +following rules, one by one in this order, until a rule determines a winner: -1. A library that is architecture compatible wins against a library that is not architecture compatible (see [**Architecture Matching**](#architecture-matching)) +1. A library that is architecture compatible wins against a library that is not architecture compatible (see + [**Architecture Matching**](#architecture-matching)) 1. A library that has better "folder name priority" wins (see [**Folder Name Priority**](#folder-name-priority)) -1. A library that is architecture optimized wins against a library that is not architecture optimized (see [**Architecture Matching**](#architecture-matching)) +1. A library that is architecture optimized wins against a library that is not architecture optimized (see + [**Architecture Matching**](#architecture-matching)) 1. A library that has a better "location priority" wins (see [**Location Priority**](#location-priority)) 1. A library that has a folder name with a better score using the "closest-match" algorithm wins 1. A library that has a folder name that comes first in alphanumeric order wins ### Architecture Matching -A library is considered **compatible** with architecture `X` if the `architectures` field in [library.properties](library-specification.md#library-metadata): +A library is considered **compatible** with architecture `X` if the `architectures` field in +[library.properties](library-specification.md#library-metadata): - explicitly contains the architecture `X` - contains the catch-all `*` - is not specified at all. -A library is considered **optimized** for architecture `X` only if the `architectures` field in library.properties explicitly contains the architecture `X`. This means that a library that is optimized for architecture `X` is also compatible with it. +A library is considered **optimized** for architecture `X` only if the `architectures` field in library.properties +explicitly contains the architecture `X`. This means that a library that is optimized for architecture `X` is also +compatible with it. Examples: -`architectures` field in `library.properties` | Compatible with `avr` | Optimized for `avr` ----|---|--- -not specified | YES | NO -`architectures=*` | YES | NO -`architectures=avr` | YES | YES -`architectures=*,avr` | YES | YES -`architectures=*,esp8266` | YES | NO -`architectures=avr,esp8266` | YES | YES -`architectures=samd` | NO | NO +| `architectures` field in `library.properties` | Compatible with `avr` | Optimized for `avr` | +| --------------------------------------------- | --------------------- | ------------------- | +| not specified | YES | NO | +| `architectures=*` | YES | NO | +| `architectures=avr` | YES | YES | +| `architectures=*,avr` | YES | YES | +| `architectures=*,esp8266` | YES | NO | +| `architectures=avr,esp8266` | YES | YES | +| `architectures=samd` | NO | NO | ### Folder Name Priority The "folder name priority" is determined as follows (in order of highest to lowest priority): -Rule | Example for `Servo.h` ----|--- -The folder name matches the include 100% | `Servo` -The folder name matches the include 100%, except with a `-master` suffix | `Servo-master` -The folder name has a matching prefix | `ServoWhatever` -The folder name has a matching suffix | `AwesomeServo` -The folder name contains the include | `AnAwesomeServoForWhatever` +| Rule | Example for `Servo.h` | +| ------------------------------------------------------------------------ | --------------------------- | +| The folder name matches the include 100% | `Servo` | +| The folder name matches the include 100%, except with a `-master` suffix | `Servo-master` | +| The folder name has a matching prefix | `ServoWhatever` | +| The folder name has a matching suffix | `AwesomeServo` | +| The folder name contains the include | `AnAwesomeServoForWhatever` | ### Location Priority The "location priority" is determined as follows (in order of highest to lowest priority): -1. The library is in a custom libraries path specified via the [`--libraries` option](../commands/arduino-cli_compile/#options) of `arduino-cli compile` (in decreasing order of priority when multiple custom paths are defined) +1. The library is in a custom libraries path specified via the + [`--libraries` option](../commands/arduino-cli_compile/#options) of `arduino-cli compile` (in decreasing order of + priority when multiple custom paths are defined) 1. The library is in the `libraries` subfolder of the IDE's sketchbook or Arduino CLI's user directory -1. The library is bundled with the board platform/core ([`{runtime.platform.path}/libraries`](platform-specification.md#global-predefined-properties)) -1. The library is bundled with the [referenced](platform-specification.md#referencing-another-core-variant-or-tool) board platform/core -1. The library is bundled with the Arduino IDE ([`{runtime.ide.path}/libraries`](platform-specification.md#global-predefined-properties)) - - This location is only used by Arduino CLI when it's located in the Arduino IDE installation folder +1. The library is bundled with the board platform/core + ([`{runtime.platform.path}/libraries`](platform-specification.md#global-predefined-properties)) +1. The library is bundled with the [referenced](platform-specification.md#referencing-another-core-variant-or-tool) + board platform/core +1. The library is bundled with the Arduino IDE + ([`{runtime.ide.path}/libraries`](platform-specification.md#global-predefined-properties)) + - This location is only used by Arduino CLI when it's located in the Arduino IDE installation folder ## Compilation -Sketches are compiled by avr-gcc and avr-g++ according to the variables in the boards.txt file of the selected board's [platform](platform-specification.md). +Sketches are compiled by avr-gcc and avr-g++ according to the variables in the boards.txt file of the selected board's +[platform](platform-specification.md). The sketch is built in a temporary directory in the system-wide temporary directory (e.g. /tmp on Linux). -Files taken as source files for the build process are .S, .c and .cpp files (including the .cpp file generated from the sketch's .ino and .pde files during the sketch pre-processing step). -Source files of the target are compiled and output with .o extensions to this build directory, as are the main sketch files and any other source files in the sketch and any source files in any libraries which are `#include`d in the sketch. +Files taken as source files for the build process are .S, .c and .cpp files (including the .cpp file generated from the +sketch's .ino and .pde files during the sketch pre-processing step). Source files of the target are compiled and output +with .o extensions to this build directory, as are the main sketch files and any other source files in the sketch and +any source files in any libraries which are `#include`d in the sketch. -Before compiling a source file, an attempt is made to reuse the previously compiled .o file, which speeds up the build process. A special .d (dependency) file provides a list of all other files included by the source. The compile step is skipped if the .o and .d files exist and have timestamps newer than the source and all the dependent files. If the source or any dependent file has been modified, or any error occurs verifying the files, the compiler is run normally, writing a new .o & .d file. After a new board is selected from the IDE's Board menu, all source files are rebuilt on the next compile. +Before compiling a source file, an attempt is made to reuse the previously compiled .o file, which speeds up the build +process. A special .d (dependency) file provides a list of all other files included by the source. The compile step is +skipped if the .o and .d files exist and have timestamps newer than the source and all the dependent files. If the +source or any dependent file has been modified, or any error occurs verifying the files, the compiler is run normally, +writing a new .o & .d file. After a new board is selected from the IDE's Board menu, all source files are rebuilt on the +next compile. -These .o files are then linked together into a static library and the main sketch file is linked against this library. Only the parts of the library needed for your sketch are included in the final .hex file, reducing the size of most sketches. +These .o files are then linked together into a static library and the main sketch file is linked against this library. +Only the parts of the library needed for your sketch are included in the final .hex file, reducing the size of most +sketches. The .hex file is the final output of the compilation which is then uploaded to the board. -If verbose output during compilation is enabled, the complete command line of each external command executed as part of the build process will be printed in the console. +If verbose output during compilation is enabled, the complete command line of each external command executed as part of +the build process will be printed in the console. ## Uploading -Sketches are uploaded by avrdude. The upload process is also controlled by variables in the boards and main preferences files. See the [Arduino platform specification](platform-specification.md) page for details. +Sketches are uploaded by avrdude. The upload process is also controlled by variables in the boards and main preferences +files. See the [Arduino platform specification](platform-specification.md) page for details. -If verbose output during upload is enabled, debugging information will be output to the console, including avrdude command lines and verbose output. +If verbose output during upload is enabled, debugging information will be output to the console, including avrdude +command lines and verbose output. diff --git a/docs/sketch-specification.md b/docs/sketch-specification.md index 332f575e834..a126a89c9ed 100644 --- a/docs/sketch-specification.md +++ b/docs/sketch-specification.md @@ -1,13 +1,17 @@ This is the specification for Arduino sketches. -The programs that run on Arduino boards are called "sketches". This term was inherited from [Processing](https://processing.org/), upon which the Arduino IDE and the core API were based. +The programs that run on Arduino boards are called "sketches". This term was inherited from +[Processing](https://processing.org/), upon which the Arduino IDE and the core API were based. ## Sketch folders and files ### Sketch root folder -Because many Arduino sketches only contain a single .ino file, it's easy to think of that file as the sketch. However, it is the folder that is the sketch. The reason is that sketches may consist of multiple code files and the folder is what groups those files into a single program. +Because many Arduino sketches only contain a single .ino file, it's easy to think of that file as the sketch. However, +it is the folder that is the sketch. The reason is that sketches may consist of multiple code files and the folder is +what groups those files into a single program. + The sketch root folder name must start with a basic letter (`A`-`Z` or `a`-`z`) or number (`0`-`9`), followed by basic letters, numbers, spaces (` `), underscores (`_`), dots (`.`) and dashes (`-`). The maximum length is 63 characters. Support for sketch folder name starting with a number was added in Arduino IDE 1.8.4. @@ -22,26 +26,30 @@ Sketches may consist of multiple code files. The following extensions are supported: -* .ino - [Arduino language](https://www.arduino.cc/reference/en/) files. -* .pde - Alternate extension for Arduino language files. This file extension is also used by Processing sketches. .ino is recommended to avoid confusion. -* .cpp - C++ files. -* .c - C Files. -* .S - Assembly language files. -* .h - Header files. +- .ino - [Arduino language](https://www.arduino.cc/reference/en/) files. +- .pde - Alternate extension for Arduino language files. This file extension is also used by Processing sketches. .ino + is recommended to avoid confusion. +- .cpp - C++ files. +- .c - C Files. +- .S - Assembly language files. +- .h - Header files. -For information about how each of these files and other parts of the sketch are used during compilation, see the [Sketch build process documentation](sketch-build-process.md). +For information about how each of these files and other parts of the sketch are used during compilation, see the +[Sketch build process documentation](sketch-build-process.md). ### `src` subfolder -The contents of the `src` subfolder are compiled recursively. Unlike the code files in the sketch root folder, these files are not shown as tabs in the IDEs. +The contents of the `src` subfolder are compiled recursively. Unlike the code files in the sketch root folder, these +files are not shown as tabs in the IDEs. -This is useful for files you don't want to expose to the sketch user via the IDE's interface. It can be used to bundle libraries with the sketch in order to make it a self-contained project. +This is useful for files you don't want to expose to the sketch user via the IDE's interface. It can be used to bundle +libraries with the sketch in order to make it a self-contained project. Arduino language files under the `src` folder are not supported. -* In Arduino IDE 1.6.5-r5 and older, no recursive compilation was done. -* In Arduino IDE 1.6.6 - 1.6.9, recursive compilation was done of all subfolders of the sketch folder. -* In Arduino IDE 1.6.10 and newer, recursive compilation is limited to the `src` subfolder of the sketch folder. +- In Arduino IDE 1.6.5-r5 and older, no recursive compilation was done. +- In Arduino IDE 1.6.6 - 1.6.9, recursive compilation was done of all subfolders of the sketch folder. +- In Arduino IDE 1.6.10 and newer, recursive compilation is limited to the `src` subfolder of the sketch folder. ### `data` subfolder @@ -49,25 +57,40 @@ The `data` folder is used to add additional files to the sketch, which will not Files added to the sketch via the Arduino IDE's **Sketch > Add File...** are placed in the `data` folder. -The Arduino IDE's **File > Save As...** only copies the code files in the sketch root folder and the full contents of the `data` folder, so any non-code files outside the `data` folder are stripped. +The Arduino IDE's **File > Save As...** only copies the code files in the sketch root folder and the full contents of +the `data` folder, so any non-code files outside the `data` folder are stripped. ### Metadata -Arduino CLI and Arduino Web Editor use a file named sketch.json, located in the sketch root folder, to store sketch metadata. +Arduino CLI and Arduino Web Editor use a file named sketch.json, located in the sketch root folder, to store sketch +metadata. -The `cpu` key contains the board configuration information. This can be set via [`arduino-cli board attach`](../commands/arduino-cli_board_attach/) or by selecting a board in the Arduino Web Editor while the sketch is open. With this configuration set, it is not necessary to specify the `--fqbn` or `--port` flags to the [`arduino-cli compile`](../commands/arduino-cli_compile/) or [`arduino-cli upload`](../commands/arduino-cli_upload/) commands when compiling or uploading the sketch. +The `cpu` key contains the board configuration information. This can be set via +[`arduino-cli board attach`](../commands/arduino-cli_board_attach/) or by selecting a board in the Arduino Web Editor +while the sketch is open. With this configuration set, it is not necessary to specify the `--fqbn` or `--port` flags to +the [`arduino-cli compile`](../commands/arduino-cli_compile/) or [`arduino-cli upload`](../commands/arduino-cli_upload/) +commands when compiling or uploading the sketch. -The `included_libs` key defines the library versions the Arduino Web Editor uses when the sketch is compiled. This is Arduino Web Editor specific because all versions of all the Library Manager libraries are pre-installed in Arduino Web Editor, while only one version of each library may be installed when using the other Arduino development software. +The `included_libs` key defines the library versions the Arduino Web Editor uses when the sketch is compiled. This is +Arduino Web Editor specific because all versions of all the Library Manager libraries are pre-installed in Arduino Web +Editor, while only one version of each library may be installed when using the other Arduino development software. ### Secrets -Arduino Web Editor has a ["Secret tab" feature](https://create.arduino.cc/projecthub/Arduino_Genuino/store-your-sensitive-data-safely-when-sharing-a-sketch-e7d0f0) that makes it easy to share sketches without accidentally exposing sensitive data (e.g., password, token). The Arduino Web Editor automatically generates macros for any identifier in the sketch which starts with `SECRET_ `and contains all uppercase characters. +Arduino Web Editor has a +["Secret tab" feature](https://create.arduino.cc/projecthub/Arduino_Genuino/store-your-sensitive-data-safely-when-sharing-a-sketch-e7d0f0) +that makes it easy to share sketches without accidentally exposing sensitive data (e.g., password, token). The Arduino +Web Editor automatically generates macros for any identifier in the sketch which starts with `SECRET_`and contains all +uppercase characters. -When you download a sketch from Arduino Web Editor that contains a Secret tab, the empty `#define` directives for the secrets are in a file named arduino_secrets.h, with an `#include` directive to that file at the top of the primary sketch file. This is hidden when viewing the sketch in Arduino Web Editor. +When you download a sketch from Arduino Web Editor that contains a Secret tab, the empty `#define` directives for the +secrets are in a file named arduino_secrets.h, with an `#include` directive to that file at the top of the primary +sketch file. This is hidden when viewing the sketch in Arduino Web Editor. ### Documentation -Image and text files in common formats which are present in the sketch root folder are displayed in tabs in the Arduino Web Editor. +Image and text files in common formats which are present in the sketch root folder are displayed in tabs in the Arduino +Web Editor. ### Sketch file structure example @@ -95,17 +118,23 @@ Foo ## Sketchbook -The Arduino IDE provides a "sketchbook" folder (analogous to Arduino CLI's "user directory"). In addition to being the place where user libraries and manually installed platforms are installed, the sketchbook is a convenient place to store sketches. Sketches in the sketchbook folder appear under the Arduino IDE's **File > Sketchbook** menu. However, there is no requirement to store sketches in the sketchbook folder. +The Arduino IDE provides a "sketchbook" folder (analogous to Arduino CLI's "user directory"). In addition to being the +place where user libraries and manually installed platforms are installed, the sketchbook is a convenient place to store +sketches. Sketches in the sketchbook folder appear under the Arduino IDE's **File > Sketchbook** menu. However, there is +no requirement to store sketches in the sketchbook folder. ## Library/Boards Manager links -A URI in a comment in the form `http://librarymanager#SEARCH_TERM` will open a search for SEARCH_TERM in [Library Manager](https://www.arduino.cc/en/guide/libraries#toc3) when clicked in the Arduino IDE. +A URI in a comment in the form `http://librarymanager#SEARCH_TERM` will open a search for SEARCH_TERM in +[Library Manager](https://www.arduino.cc/en/guide/libraries#toc3) when clicked in the Arduino IDE. -A URI in a comment in the form `http://boardsmanager#SEARCH_TERM` will open a search for SEARCH_TERM in [Boards Manager](https://www.arduino.cc/en/Guide/Cores) when clicked in the Arduino IDE. +A URI in a comment in the form `http://boardsmanager#SEARCH_TERM` will open a search for SEARCH_TERM in +[Boards Manager](https://www.arduino.cc/en/Guide/Cores) when clicked in the Arduino IDE. This can be used to offer the user an easy way to install dependencies of the sketch. -This feature is only available when using the Arduino IDE, so be sure to provide supplementary documentation to help the users of other development software install the sketch dependencies. +This feature is only available when using the Arduino IDE, so be sure to provide supplementary documentation to help the +users of other development software install the sketch dependencies. This feature was added in Arduino IDE 1.6.9. @@ -122,5 +151,5 @@ This feature was added in Arduino IDE 1.6.9. ## See also -* [Sketch build process documentation](sketch-build-process.md) -* [Style guide for example sketches](http://arduino.cc/en/Reference/StyleGuide) +- [Sketch build process documentation](sketch-build-process.md) +- [Style guide for example sketches](http://arduino.cc/en/Reference/StyleGuide) diff --git a/i18n/README.md b/i18n/README.md index 43d07d4f5ac..311da108373 100644 --- a/i18n/README.md +++ b/i18n/README.md @@ -2,7 +2,8 @@ ## Usage -In the source code, use the function `i18n.Tr("message", ...args)` to get a localized string. This tool parses the source using the `go/ast` package to generate the `en` locale using these messages. +In the source code, use the function `i18n.Tr("message", ...args)` to get a localized string. This tool parses the +source using the `go/ast` package to generate the `en` locale using these messages. ## Updating messages to reflect code changes @@ -25,11 +26,11 @@ task i18n:update Set the following environment variables according to the project -|Variable|Description| -|--------|-----------| -|TRANSIFEX_PROJECT|Name of the transifex project| -|TRANSIFEX_RESOURCE|Name of the transifex translation resource| -|TRANSIFEX_API_KEY|API Key to access the transifex project| +| Variable | Description | +| ------------------ | ------------------------------------------ | +| TRANSIFEX_PROJECT | Name of the transifex project | +| TRANSIFEX_RESOURCE | Name of the transifex translation resource | +| TRANSIFEX_API_KEY | API Key to access the transifex project | ### Push diff --git a/mkdocs.yml b/mkdocs.yml index 6f61bc3907d..73f50486dbc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,7 +6,7 @@ site_url: https://arduino.github.io/arduino-cli/ # Repository repo_name: arduino/arduino-cli repo_url: https://github.com/arduino/arduino-cli -edit_uri: '' +edit_uri: "" # Copyright copyright: Copyright 2020 ARDUINO SA (http://www.arduino.cc/) @@ -50,6 +50,9 @@ markdown_extensions: - pymdownx.tasklist: custom_checkbox: true - pymdownx.tilde + - mdx_truly_sane_lists: + nested_indent: 2 + truly_sane: true # Navigation nav: @@ -60,48 +63,48 @@ nav: - CONTRIBUTING.md - FAQ.md - Command reference: - - arduino-cli: commands/arduino-cli.md - - board: commands/arduino-cli_board.md - - board attach: commands/arduino-cli_board_attach.md - - board details: commands/arduino-cli_board_details.md - - board list: commands/arduino-cli_board_list.md - - board listall: commands/arduino-cli_board_listall.md - - burn-bootloader: commands/arduino-cli_burn-bootloader.md - - cache: commands/arduino-cli_cache.md - - cache clean: commands/arduino-cli_cache_clean.md - - compile: commands/arduino-cli_compile.md - - completion: commands/arduino-cli_completion.md - - config: commands/arduino-cli_config.md - - config dump: commands/arduino-cli_config_dump.md - - config init: commands/arduino-cli_config_init.md - - core: commands/arduino-cli_core.md - - core download: commands/arduino-cli_core_download.md - - core install: commands/arduino-cli_core_install.md - - core list: commands/arduino-cli_core_list.md - - core search: commands/arduino-cli_core_search.md - - core uninstall: commands/arduino-cli_core_uninstall.md - - core update index: commands/arduino-cli_core_update-index.md - - core upgrade: commands/arduino-cli_core_upgrade.md - - daemon: commands/arduino-cli_daemon.md - - debug: commands/arduino-cli_debug.md - - lib: commands/arduino-cli_lib.md - - lib deps: commands/arduino-cli_lib_deps.md - - lib download: commands/arduino-cli_lib_download.md - - lib install: commands/arduino-cli_lib_install.md - - lib list: commands/arduino-cli_lib_list.md - - lib search: commands/arduino-cli_lib_search.md - - lib uninstall: commands/arduino-cli_lib_uninstall.md - - lib update-index: commands/arduino-cli_lib_update-index.md - - lib upgrade: commands/arduino-cli_lib_upgrade.md - - sketch: commands/arduino-cli_sketch.md - - sketch new: commands/arduino-cli_sketch_new.md - - upload: commands/arduino-cli_upload.md - - version: commands/arduino-cli_version.md + - arduino-cli: commands/arduino-cli.md + - board: commands/arduino-cli_board.md + - board attach: commands/arduino-cli_board_attach.md + - board details: commands/arduino-cli_board_details.md + - board list: commands/arduino-cli_board_list.md + - board listall: commands/arduino-cli_board_listall.md + - burn-bootloader: commands/arduino-cli_burn-bootloader.md + - cache: commands/arduino-cli_cache.md + - cache clean: commands/arduino-cli_cache_clean.md + - compile: commands/arduino-cli_compile.md + - completion: commands/arduino-cli_completion.md + - config: commands/arduino-cli_config.md + - config dump: commands/arduino-cli_config_dump.md + - config init: commands/arduino-cli_config_init.md + - core: commands/arduino-cli_core.md + - core download: commands/arduino-cli_core_download.md + - core install: commands/arduino-cli_core_install.md + - core list: commands/arduino-cli_core_list.md + - core search: commands/arduino-cli_core_search.md + - core uninstall: commands/arduino-cli_core_uninstall.md + - core update index: commands/arduino-cli_core_update-index.md + - core upgrade: commands/arduino-cli_core_upgrade.md + - daemon: commands/arduino-cli_daemon.md + - debug: commands/arduino-cli_debug.md + - lib: commands/arduino-cli_lib.md + - lib deps: commands/arduino-cli_lib_deps.md + - lib download: commands/arduino-cli_lib_download.md + - lib install: commands/arduino-cli_lib_install.md + - lib list: commands/arduino-cli_lib_list.md + - lib search: commands/arduino-cli_lib_search.md + - lib uninstall: commands/arduino-cli_lib_uninstall.md + - lib update-index: commands/arduino-cli_lib_update-index.md + - lib upgrade: commands/arduino-cli_lib_upgrade.md + - sketch: commands/arduino-cli_sketch.md + - sketch new: commands/arduino-cli_sketch_new.md + - upload: commands/arduino-cli_upload.md + - version: commands/arduino-cli_version.md - gRPC reference: - - commands: rpc/commands.md - - monitor: rpc/monitor.md - - settings: rpc/settings.md - - debug: rpc/debug.md + - commands: rpc/commands.md + - monitor: rpc/monitor.md + - settings: rpc/settings.md + - debug: rpc/debug.md - configuration.md - Integration options: integration-options.md - sketch-build-process.md diff --git a/requirements_docs.txt b/requirements_docs.txt index c2fb2ccf2aa..65255692751 100644 --- a/requirements_docs.txt +++ b/requirements_docs.txt @@ -3,3 +3,4 @@ mkdocs-material<5 mike==0.5.1 gitpython click<7.2 +mdx_truly_sane_lists==1.2 diff --git a/test/README.md b/test/README.md index 2ac0c32b889..c05d5d8621c 100644 --- a/test/README.md +++ b/test/README.md @@ -1,7 +1,7 @@ # Integration tests -This dir contains integration tests, aimed to test the Command Line Interface -and its output from a pure user point of view. +This dir contains integration tests, aimed to test the Command Line Interface and its output from a pure user point of +view. ## Installation @@ -25,8 +25,8 @@ task test-integration This will create and install all necessary dependencies if not already existing and then run integrations tests. -To run specific modules you must run `pytest` from the virtual environment created by Poetry. -If dependencies have not already been installed first run `poetry install`. +To run specific modules you must run `pytest` from the virtual environment created by Poetry. If dependencies have not +already been installed first run `poetry install`. ```shell poetry run pytest test/test_lib.py @@ -54,7 +54,8 @@ To run lint check from the project's root folder: task python:check ``` -This will run `flake8` automatically and return any error in the code formatting, if not already installed it will also install integration tests dependencies. +This will run `flake8` automatically and return any error in the code formatting, if not already installed it will also +install integration tests dependencies. In case of linting errors you should be able to solve most of them by automatically formatting with: