Skip to content

Commit 797c700

Browse files
jaenrig-ifxjaenrig-ifx
committed
docs: Added arduino-packager docs.
Signed-off-by: jaenrig-ifx <[email protected]>
1 parent 5b94bbf commit 797c700

File tree

2 files changed

+225
-3
lines changed

2 files changed

+225
-3
lines changed

‎docs/compile-examples/getting-started.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Before you start, make sure you satisfy the following prerequisites:
1212

1313
- Your Arduino asset (library or core) is hosted in a GitHub repository.
1414
- GitHub Actions is enabled in your repository. Check the `GitHub docs <https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#managing-github-actions-permissions-for-your-repository>`_ to learn how to enable it.
15-
- If your asset is an Arduino core, first you need to `configure the repository <df>`_ to be able to generate the core package with the ``core-packager.py`` tool.
15+
- If your asset is an Arduino core, first you need to :doc:`configure the repository <../scripts/arduino-packager>` to be able to generate the core package with the ``core-packager.py`` tool.
1616

1717
Enabling the reusable workflow
1818
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

‎docs/scripts/arduino-packager.rst

Lines changed: 224 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,227 @@
11
arduino-packager
22
================
33

4-
In the case of Arduino cores, it also takes care of packaging the core assets, which includes the sources and
5-
the `package index manifest <https://docs.arduino.cc/arduino-cli/package_index_json-specification/>`_ with the core metadata, to be able to be installed by the Arduino IDE or CLI.
4+
The ``arduino-packager`` script generates the package assets for Arduino cores installation.
5+
These include:
6+
7+
- The archive *.zip* file with the core `required sources and metafiles <https://docs.arduino.cc/arduino-cli/platform-specification>`_.
8+
- The `package index manifest <https://docs.arduino.cc/arduino-cli/package_index_json-specification/>`_ file, which contains the information required by Arduino (IDE and CLI) to install the core.
9+
10+
It requires two files for the asset generation:
11+
12+
- **The core packager YAML file**
13+
14+
This file is used by the ``arduino-packager`` in both the creation of the sources archive and the package index JSON file.
15+
It specifies which files need to be included in the package, and provides some of the field values of the package index JSON.
16+
See section `Packager config YAML specification`_ to check all the configurable parameters.
17+
18+
- **The package index manifest template**
19+
20+
It includes the JSON schema that needs to be filled in for every release. Some of the keys are already pre-filled. These are constant for every release.
21+
22+
The rest of the empty keys will be added by the ``arduino-packager.py`` script based on the core sources archive and the provided packager configuration YAML.
23+
24+
25+
.. note::
26+
27+
Please locate these 2 files inside the ``package`` directory of the core root path. This is the default location where the tool will look for them.
28+
29+
30+
Additionally, the script will also include all the previous releases (``platforms`` key) based on the JSON package index manifest of the previous release.
31+
This way, the user will have access to all the existing versions of the core.
32+
33+
Packager config YAML specification
34+
----------------------------------
35+
36+
The YAML file supports the following keys:
37+
38+
- package-name:
39+
The name of the core package archive.
40+
41+
- include:
42+
List of files and directories to include in the core package
43+
archive.
44+
45+
- index-name:
46+
The name of the index file without the ".json" extension.
47+
48+
- server:
49+
The server information for uploading the package.
50+
This is open to different specifications and approaches
51+
for the package sources archive and package index file hosting.
52+
Currently, the only one supported is:
53+
54+
**GitHub**
55+
56+
The GitHub server should have the following keys:
57+
58+
- type:
59+
github
60+
- owner:
61+
The owner of the repository (user name or organization)
62+
- repo:
63+
The repository name
64+
65+
From this information, we can generate:
66+
67+
- The URL to download the package.
68+
- The URL of the package index JSON file.
69+
70+
71+
Optional keys:
72+
73+
- exclude:
74+
Specific files or subdirectories to exclude from any of the
75+
directories in the include list.
76+
77+
This exclude list will be processed after the include list.
78+
Therefore, if a file is in both the exclude and
79+
include lists, it will be excluded.
80+
81+
- index-template:
82+
The template for the package index file.
83+
If not provided, the expected default value is:
84+
"package/<index-name>.template.json"
85+
86+
Reference example YAML file:
87+
88+
.. code:: yaml
89+
90+
package-name: arduino-core-vendor-product
91+
include:
92+
- cores
93+
- libraries
94+
- variants
95+
- boards.txt
96+
- platform.txt
97+
- LICENSE.md
98+
- README.md
99+
- post_install.sh
100+
index-name: package_vendor_product_index
101+
server:
102+
type: github
103+
owner: vendor-owner
104+
repo: arduino-core-repo-name
105+
106+
.. note::
107+
108+
Most of the configuration data in the YAML file can have a default value and/or can be auto-discovered.
109+
Future versions of the scripts will try to provide such features.
110+
This will simplify the configuration as much as possible, while providing alternatives through the YAML file to override the defaults.
111+
112+
Package index manifest template
113+
--------------------------------
114+
115+
The package index manifest template is a JSON file that contains the schema for the package index manifest.
116+
Find the description of each field in the `Arduino CLI package index JSON specification <https://docs.arduino.cc/arduino-cli/package_index_json-specification>`_.
117+
This is the schema with the pre-filled keys containing dummy values, which can be fixed for every release:
118+
119+
.. code:: json
120+
121+
{
122+
"packages": [
123+
{
124+
"name": "company_vendor",
125+
"maintainer": "company_or_person_maintainer",
126+
"websiteURL": "url_to_the_documentation",
127+
"email": "[email protected]",
128+
"platforms": [
129+
{
130+
"name": "<vendor> <product> Boards",
131+
"architecture": "<product_architecture>",
132+
"version": "",
133+
"category": "Contributed",
134+
"url": "",
135+
"archiveFileName": "",
136+
"checksum": "",
137+
"size": "",
138+
"help": {
139+
"online": ""
140+
},
141+
"boards": [
142+
{
143+
"name": "board_a_name"
144+
},
145+
{
146+
"name": "board_b_name"
147+
}
148+
],
149+
"toolsDependencies": [
150+
{
151+
"packager": "vendor",
152+
"name": "tool_x",
153+
"version": "x.y.z"
154+
},
155+
{
156+
"packager": "company",
157+
"name": "tool_a",
158+
"version": "a.b.c"
159+
}
160+
]
161+
}
162+
],
163+
"tools": [
164+
{
165+
"name": "tool_x",
166+
"version": "x.y.z",
167+
"systems": [
168+
{
169+
"host": "i686-mingw32",
170+
"archiveFileName": "tool_x-x.y.z-windows.zip",
171+
"url": "https://url-to-package/tool_x-x.y.z-windows.zip",
172+
"checksum": "SHA-256:a96002b4aebbd89b1ace6a2da3f591d27d168fe56c1decd401bfb7a88d509260",
173+
"size": "305588533"
174+
},
175+
{
176+
"host": "x86_64-pc-linux-gnu",
177+
"archiveFileName": "tool_x-x.y.z-linux.tar.gz",
178+
"url": "https://url-to-package/tool_x-x.y.z-linux.tar.gz",
179+
"checksum": "SHA-256:76fb2d76080c3c2966983d8d8053cb7082416b83d8f5f6caa3d69bc8287d7846",
180+
"size": "212727150"
181+
},
182+
{
183+
"host": "x86_64-apple-darwin",
184+
"archiveFileName": "tool_x-x.y.z-macosx.tar.gz",
185+
"url": "https://url-to-package/tool_x-x.y.z-macosx.tar.gz",
186+
"checksum": "SHA-256:081417273428cd7c929e8206c823c8681e53c84ee86f8ce95f71e726702e7d75",
187+
"size": "206451774"
188+
}
189+
]
190+
},
191+
{
192+
"name": "tool_a",
193+
"version": "a.b.c",
194+
"systems": [
195+
{
196+
"host": "i686-mingw32",
197+
"archiveFileName": "tool_a-a.b.c-windows.zip",
198+
"url": "https://url-to-package/tool_a-a.b.c-windows.zip",
199+
"checksum": "SHA-256:858d7370ea29bd70f22a017976248c7df82076d401a05420b1a479ebadb1f7b2",
200+
"size": "4932550"
201+
},
202+
{
203+
"host": "x86_64-pc-linux-gnu",
204+
"archiveFileName": "tool_a-a.b.c-linux.tar.gz",
205+
"url": "https://url-to-package/tool_a-a.b.c-linux.tar.gz",
206+
"checksum": "SHA-256:2ea4721039cbfd3859ddac87eda8c3a10284c7404a77fdcb69e9a96378ea880b",
207+
"size": "4620637"
208+
},
209+
{
210+
"host": "x86_64-apple-darwin",
211+
"archiveFileName": "tool_a-a.b.c-macos.zip",
212+
"url": "https://url-to-package/tool_a-a.b.c-macos.zip",
213+
"checksum": "SHA-256:563dd0ad0dfabc05a8832c068e85b330d93248cc907978b29c3d3d95710dc077",
214+
"size": "4901567"
215+
}
216+
]
217+
}
218+
]
219+
}
220+
]
221+
}
222+
223+
By default, the template will be searched in the ``package`` directory of the core root path, with the name ``<index-name>.template.json``.
224+
225+
You can override this by providing the ``index-template`` key in the packager YAML file.
226+
227+

0 commit comments

Comments
 (0)