You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+52-47Lines changed: 52 additions & 47 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,11 +7,13 @@ This repository is for the **GitHub Action** to run [`arduino_ci`](https://githu
7
7
8
8
- Contributions to your Arduino library are tested automatically, _without_ the need for hardware present
9
9
- Example sketches in your `examples/` directory are compiled automatically, to detect broken code in the default branch
10
-
-`library.properties` is scanned for correctness
10
+
11
+
### See Also
12
+
*[`arduino-lint` action](https://github.com/marketplace/actions/arduino-arduino-lint-action) for verifying metadata (e.g. `library.properties`) and structural aspects of a library
11
13
12
14
## Adding Arduino CI Pull Request Tests To Your Project
13
15
14
-
1. Create a new YAML file in your repository's `.github/workflows` directory, e.g. `.github/workflows/arduino_test_runner.yml`
16
+
1. Create a new YAML file in your repository's `.github/workflows` directory, e.g. `.github/workflows/arduino_ci.yml`
15
17
2. Copy an example workflow from below into that new file, no extra configuration required
16
18
3. Commit that file to a new branch
17
19
4. Open up a pull request and observe the action working
@@ -20,7 +22,15 @@ This repository is for the **GitHub Action** to run [`arduino_ci`](https://githu
20
22
21
23
### Configuring a Workflow to Use the GitHub Action
22
24
23
-
These contents for `.github/workflows/arduino_test_runner.yml` should work for most people.
25
+
There are several ways to specify what version of the action to run.
`Arduino-CI/action@v0.1.2` | exact version | Complete control | Adopt new versions manually, which may be tiresome if you have many libraries
30
+
`Arduino-CI/action@latest` | bleeding-edge unreleased `arduino_ci` version | Receive latest features & fixes automatically | High risk of encountering breaking changes or new bugs
31
+
`Arduino-CI/action@stable-1.x` | use highest available `arduino_ci` version that is < `2.0.0` | Receive latest features & fixes automatically, but avoids breaking changes | Not a 100% guarantee against unintended CI changes
32
+
33
+
Using `Arduino-CI/action@stable-1.x` is **recommended**, so the contents listed below for `.github/workflows/arduino_ci.yml` should work for most users.
24
34
25
35
```yml
26
36
---
@@ -34,8 +44,16 @@ jobs:
34
44
35
45
steps:
36
46
- uses: actions/checkout@v2
37
-
- uses: Arduino-CI/action@v0.1.2#v0.1.2 or the latest version
47
+
- uses: Arduino-CI/action@stable-1.x#or latest, or a pinned version
38
48
env:
49
+
# Not all libraries are in the root directory of a repository.
50
+
# Specifying the path of the library here (relative to the root
51
+
# of the repository) will adjust that.
52
+
#
53
+
# The default is the current directory
54
+
#
55
+
# USE_SUBDIR: .
56
+
39
57
# Not all libraries include examples or unit tests. The default
40
58
# behavior of arduino_ci is to assume that "if the files don't
41
59
# exist, then they were not MEANT to exist". In other words,
@@ -45,38 +63,23 @@ jobs:
45
63
#
46
64
# If you'd rather have the test runner fail the test in the
47
65
# absence of either tests or examples, uncommenting either of
48
-
# the following lines (as appropriate) will enforce that.
66
+
# the following variables to 'true' (as appropriate) will
67
+
# enforce that.
49
68
#
50
69
# EXPECT_EXAMPLES: false
51
70
# EXPECT_UNITTESTS: false
52
71
53
-
# Scanning library.properties for issues is a relatively new
54
-
# feature, and we may not have implemented it perfectly just
55
-
# yet.
56
-
#
57
-
# If you find that it incorrectly fails your library, you can
58
-
# skip it. (Please open an issue against arduino_ci as well
59
-
# so that it can be fixed.)
60
-
#
61
-
# SKIP_LIBRARY_PROPERTIES: false
62
-
63
-
# Not all libraries are in the root directory of a repository.
64
-
# Specifying the path of the library here (relative to the root
65
-
# of the repository) will adjust that.
66
-
#
67
-
# The default is the current directory
68
-
#
69
-
# USE_SUBDIR: .
70
-
71
72
# Although dependencies will be installed automatically via the
72
73
# library manager, your library under test may require an
73
74
# unofficial version of a dependency. In those cases, the custom
74
75
# libraries must be insalled prior to the test execution; those
75
76
# installation commands should be placed in a shell script (that
76
-
# will be executed by /bin/sh) and the shell script in your repo.
77
+
# will be executed by /bin/sh) stored in your library.
77
78
#
78
79
# Then, set this variable to the path to that file (relative to
79
-
# the repository root)
80
+
# the root of your repository). The script will be run from
81
+
# within the Arduino libraries directory; you should NOT attempt
82
+
# to find that directory nor change to it from within the script.
80
83
#
81
84
# CUSTOM_INIT_SCRIPT: install_dependencies.sh
82
85
```
@@ -119,11 +122,12 @@ The same Docker image used by the GitHub action is available for local testing,
119
122
120
123
### Your Arduino Libraries directory has everything set up just right; you just want to get up and running and not worry about dependencies at all
Your library under test, called `mylib` | `/pathTo/Arduino/libraries/mylib`
129
+
A custom library `mylib` depends on | `/pathTo/Arduino/libraries/custom`
130
+
127
131
128
132
In this situation, you've got a mix of libraries installed locally (the one that will be tested amongst any possible dependencies), and they all work as expected (even though you're not quite sure all of them are up to date, nor whether they have local modifications that aren't part of the official library release). This setup won't work in CI, but by volume-mounting the libraries directory into the container and using your own library as the working directory, you can ensure that arduino_ci is using the _exact_ same set of dependencies.
129
133
@@ -141,10 +145,10 @@ docker run --rm \
141
145
142
146
### Your Arduino Library uses only "official" library versions as dependencies
Your library under test, called `mylib` | `/pathTo/Arduino/libraries/mylib`
148
152
149
153
In this situation, the only libraries you need for your library to work are those that you've downloaded directly from the library manager and no special modifications need to be made. We simply volume mount the library under test into the container, set that directory to be the working directory, and let the `arduino_ci` test runner install the dependencies directly.
150
154
@@ -160,12 +164,12 @@ docker run --rm \
160
164
161
165
### Your Arduino Library uses libraries or versions as dependencies that can't be installed by name from the Arduino library manager (but you wrote a script to install them automatically)
Your library under test, called `mylib` | `/pathTo/Arduino/libraries/mylib`
171
+
Shell script to install `custom` library | `/pathTo/Arduino/libraries/mylib/install.sh`
172
+
A custom library `mylib` depends on| `/pathTo/Arduino/libraries/custom`
169
173
170
174
In this situation, you have a custom library that can't be installed by the library manager. Fortunately, you've supplied an `install.sh` script that will download and unpack a library to the current working directory (which Arduino CI's test runner will run from inside the container's Arduino libraries directory). Note the _relative_ path used for `install.sh`.
171
175
@@ -180,14 +184,15 @@ docker run --rm \
180
184
181
185
### Your Arduino Library is a subdirectory of a monorepo, you need libraries or versions as dependencies that can't be installed by name from the Arduino library manager, you wrote a script to install them automatically
0 commit comments