diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 64204542882..3fa03de617e 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -9,6 +9,7 @@ See [how to contribute](https://arduino.github.io/arduino-cli/latest/CONTRIBUTIN - [ ] Tests for the changes have been added (for bug fixes / features) - [ ] Docs have been added / updated (for bug fixes / features) - [ ] `UPGRADING.md` has been updated with a migration guide (for breaking changes) +- [ ] `configuration.schema.json` updated if new parameters are added. ## What kind of change does this PR introduce? diff --git a/.github/workflows/publish-go-nightly-task.yml b/.github/workflows/publish-go-nightly-task.yml index 12c4f33c609..c5070dc83b7 100644 --- a/.github/workflows/publish-go-nightly-task.yml +++ b/.github/workflows/publish-go-nightly-task.yml @@ -36,6 +36,7 @@ jobs: - Linux_ARM64 - macOS_64bit - macOS_ARM64 + - jsonschema steps: - name: Checkout repository diff --git a/.github/workflows/publish-go-tester-task.yml b/.github/workflows/publish-go-tester-task.yml index 73a6c57491a..37c3be01a6f 100644 --- a/.github/workflows/publish-go-tester-task.yml +++ b/.github/workflows/publish-go-tester-task.yml @@ -111,6 +111,9 @@ jobs: - task: protoc:collect path: "*_proto.zip" name: rpc-protocol-files + - task: dist:jsonschema + path: "*configuration.schema.json" + name: configuration-schema steps: - name: Checkout repository @@ -146,7 +149,6 @@ jobs: steps: - name: Download build artifacts uses: actions/download-artifact@v3 - - name: Output checksum run: | TAG="${{ needs.package-name-prefix.outputs.prefix }}git-snapshot" diff --git a/.github/workflows/release-go-task.yml b/.github/workflows/release-go-task.yml index b059d60925d..af177d0d429 100644 --- a/.github/workflows/release-go-task.yml +++ b/.github/workflows/release-go-task.yml @@ -253,8 +253,11 @@ jobs: - name: Collect proto files run: task protoc:collect + - name: Add configuration JSON schema + run: task dist:jsonschema + - name: Create checksum file - working-directory: ${{ env.DIST_DIR}} + working-directory: ${{ env.DIST_DIR }} run: | TAG=${{ needs.create-release-artifacts.outputs.version }} sha256sum ${{ env.PROJECT_NAME }}_${TAG}* > ${TAG}-checksums.txt diff --git a/.gitignore b/.gitignore index 3d695480cd0..70751f882c6 100644 --- a/.gitignore +++ b/.gitignore @@ -28,6 +28,7 @@ venv /docsgen/arduino-cli.exe /docs/rpc/*.md /docs/commands/*.md +/docs/configuration.schema.json # Delve debugger binary file __debug_bin diff --git a/DistTasks.yml b/DistTasks.yml index eb9dcd4f9e1..ebc0db6424a 100644 --- a/DistTasks.yml +++ b/DistTasks.yml @@ -251,3 +251,9 @@ tasks: CONTAINER_TAG: "{{.GO_VERSION}}-darwin-arm64-debian10" PACKAGE_PLATFORM: "macOS_ARM64" PACKAGE_NAME: "{{.PROJECT_NAME}}_{{.VERSION}}_{{.PACKAGE_PLATFORM}}.tar.gz" + + jsonschema: + desc: Copy the JSON schema to dist folder + cmds: + - mkdir --parents {{.DIST_DIR}} + - cp ./configuration/configuration.schema.json {{.DIST_DIR}}/{{.PROJECT_NAME}}_{{.VERSION}}_configuration.schema.json diff --git a/Taskfile.yml b/Taskfile.yml index 0a37a4a8a76..380b0898867 100755 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -9,6 +9,7 @@ tasks: deps: - task: go:cli-docs - task: protoc:docs + - task: docs:include-configuration-json-schema cmds: - task: general:format-prettier @@ -218,6 +219,11 @@ tasks: - '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,settings.md --proto_path=rpc ./rpc/cc/arduino/cli/settings/v1/*.proto' - '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,debug.md --proto_path=rpc ./rpc/cc/arduino/cli/debug/v1/*.proto' + docs:include-configuration-json-schema: + desc: Copy configuration JSON schema to make it available in documentation + cmds: + - cp ./configuration/configuration.schema.json ./docs/configuration.schema.json + protoc:check: desc: Perform linting of the protobuf definitions cmds: diff --git a/configuration/configuration.schema.json b/configuration/configuration.schema.json new file mode 100644 index 00000000000..dae8cf66a6d --- /dev/null +++ b/configuration/configuration.schema.json @@ -0,0 +1,161 @@ +{ + "title": "Arduino CLI configuration schema", + "description": "Describe the parameters available for the Arduino CLI configuration file. This schema should be considered unstable at this moment, it is not used by the CLI to validate input configuration", + "$schema": "http://json-schema.org/draft-06/schema#", + "properties": { + "board_manager": { + "description": "", + "properties": { + "additional_urls": { + "description": "the URLs to any additional Boards Manager package index files needed for your boards platforms.", + "type": "array", + "items": { + "type": "string", + "format": "uri" + } + } + }, + "type": "object" + }, + "build_cache": { + "description": "configuration options related to the compilation cache", + "properties": { + "compilations_before_purge": { + "description": "interval, in number of compilations, at which the cache is purged, defaults to `10`. When `0` the cache is never purged.", + "type": "integer", + "minimum": 0 + }, + "ttl": { + "description": "cache expiration time of build folders. If the cache is hit by a compilation the corresponding build files lifetime is renewed. The value format must be a valid input for time.ParseDuration(), defaults to `720h` (30 days)", + "oneOf": [ + { + "type": "integer", + "minimum": 0 + }, + { + "type": "string", + "pattern": "^\\+?([0-9]?\\.?[0-9]+(([nuµm]?s)|m|h))+$" + } + ] + } + }, + "type": "object" + }, + "daemon": { + "description": "options related to running Arduino CLI as a [gRPC] server.", + "properties": { + "port": { + "description": "TCP port used for gRPC client connections.", + "type": "string", + "pattern": "^[0-9]+$" + } + }, + "type": "object" + }, + "directories": { + "description": "directories used by Arduino CLI.", + "properties": { + "builtin": { + "description": "", + "properties": { + "libraries": { + "description": "the libraries in this directory will be available to all platforms without the need for the user to install them, but with the lowest priority over other installed libraries with the same name, it's the equivalent of the Arduino IDE's bundled libraries directory.", + "type": "string" + }, + "tools": { + "description": "it's a list of directories of tools that will be available to all platforms without the need for the user to install them, it's the equivalent of the Arduino IDE 1.x bundled tools directory.", + "type": "array", + "items": { + "type": "string" + } + } + }, + "type": "object" + }, + "data": { + "description": "directory used to store Boards/Library Manager index files and Boards Manager platform installations.", + "type": "string" + }, + "downloads": { + "description": "directory used to stage downloaded archives during Boards/Library Manager installations.", + "type": "string" + }, + "user": { + "description": "the equivalent of the Arduino IDE's [\"sketchbook\" directory][sketchbook directory]. Library Manager installations are made to the `libraries` subdirectory of the user directory.", + "type": "string" + } + }, + "type": "object" + }, + "library": { + "description": "configuration options relating to Arduino libraries.", + "properties": { + "enable_unsafe_install": { + "description": "set to `true` to enable the use of the `--git-url` and `--zip-file` flags with [`arduino-cli lib install`][arduino cli lib install]. These are considered \"unsafe\" installation methods because they allow installing files that have not passed through the Library Manager submission process.", + "type": "boolean" + } + }, + "type": "object" + }, + "locale": { + "description": "the language used by Arduino CLI to communicate to the user, the parameter is the language identifier in the standard POSIX format `[_[.]]` (for example `it` or `it_IT`, or `it_IT.UTF-8`).", + "type": "string" + }, + "logging": { + "description": "configuration options for Arduino CLI's logs.", + "properties": { + "file": { + "description": "path to the file where logs will be written.", + "type": "string" + }, + "format": { + "description": "output format for the logs. Allowed values are `text` or `json`.", + "type": "string", + "enum": ["text", "json"] + }, + "level": { + "description": "messages with this level and above will be logged. Valid levels are: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`.", + "type": "string", + "enum": ["trace", "debug", "info", "warn", "error", "fatal", "panic"] + } + }, + "type": "object" + }, + "metrics": { + "description": "settings related to the collection of data used for continued improvement of Arduino CLI.", + "properties": { + "addr": { + "description": "TCP port used for metrics communication.", + "type": "string" + }, + "enabled": { + "description": "controls the use of metrics.", + "type": "boolean" + } + }, + "type": "object" + }, + "sketch": { + "description": "configuration options relating to [Arduino sketches][sketch specification].", + "properties": { + "always_export_binaries": { + "description": "set to `true` to make [`arduino-cli compile`][arduino-cli compile] always save binaries to the sketch folder. This is the equivalent of using the [`--export-binaries`][arduino-cli compile options] flag.", + "type": "boolean" + } + }, + "type": "object" + }, + "updater": { + "description": "configuration options related to Arduino CLI updates", + "properties": { + "enable_notification": { + "description": "set to `false` to disable notifications of new Arduino CLI releases, defaults to `true`", + "type": "boolean", + "default": true + } + }, + "type": "object" + } + }, + "type": "object" +} diff --git a/configuration/configuration_schema_test.go b/configuration/configuration_schema_test.go new file mode 100644 index 00000000000..afc961ee52f --- /dev/null +++ b/configuration/configuration_schema_test.go @@ -0,0 +1,19 @@ +package configuration + +import ( + "io/ioutil" + "testing" + + "github.com/stretchr/testify/require" + "github.com/xeipuuv/gojsonschema" +) + +func TestConfigurationSchemaValidity(t *testing.T) { + schemaBytes, err := ioutil.ReadFile("configuration.schema.json") + require.NoError(t, err) + + jl := gojsonschema.NewBytesLoader(schemaBytes) + sl := gojsonschema.NewSchemaLoader() + _, err = sl.Compile(jl) + require.NoError(t, err) +} diff --git a/docs/configuration.md b/docs/configuration.md index f60402bf212..b03cbaa3e25 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -146,6 +146,11 @@ Doing the same using a TOML format file: additional_urls = [ "https://downloads.arduino.cc/packages/package_staging_index.json" ] ``` +#### JSON schema + +The configuration file [JSON schema][configuration-schema] can be used to independently validate the file content. This +schema should be considered unstable in this version. + [grpc]: https://grpc.io [sketchbook directory]: sketch-specification.md#sketchbook [arduino cli lib install]: commands/arduino-cli_lib_install.md @@ -164,3 +169,4 @@ additional_urls = [ "https://downloads.arduino.cc/packages/package_staging_index [java properties file]: https://en.wikipedia.org/wiki/.properties [hcl]: https://github.com/hashicorp/hcl [ini]: https://en.wikipedia.org/wiki/INI_file +[configuration-schema]: ./configuration.schema.json diff --git a/docsgen/go.sum b/docsgen/go.sum index b458f5af5f2..bf4fea78449 100644 --- a/docsgen/go.sum +++ b/docsgen/go.sum @@ -331,6 +331,9 @@ github.com/ulikunitz/xz v0.5.11 h1:kpFauv27b6ynzBNT/Xy+1k+fK4WswhN/6PN5WhFAGw8= github.com/ulikunitz/xz v0.5.11/go.mod h1:nbz6k7qbPmH4IRqmfOplQw/tblSgqTqBwxkY0oWt/14= github.com/xanzy/ssh-agent v0.2.1 h1:TCbipTQL2JiiCprBWx9frJ2eJlCYT00NmctrHxVAr70= github.com/xanzy/ssh-agent v0.2.1/go.mod h1:mLlQY/MoOhWBj+gOGMQkOeiEvkx+8pJSI+0Bx9h2kr4= +github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f h1:J9EGpcZtP0E/raorCMxlFGSTBrsSlaDGf3jU/qvAE2c= +github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 h1:EzJWgHovont7NscjpAxXsDA8S8BMYve8Y5+7cuRE7R0= +github.com/xeipuuv/gojsonschema v1.2.0 h1:LhYJRs+L4fBtjZUfuSZIKGeVu0QRy8e5Xi7D17UxZ74= github.com/yuin/goldmark v1.1.25/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74= github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74= github.com/yuin/goldmark v1.1.32/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74= diff --git a/go.mod b/go.mod index d7c40152503..912d04ab767 100644 --- a/go.mod +++ b/go.mod @@ -49,6 +49,7 @@ require ( require ( github.com/rogpeppe/go-internal v1.3.0 + github.com/xeipuuv/gojsonschema v1.2.0 go.bug.st/testifyjson v1.1.1 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211 gopkg.in/yaml.v3 v3.0.1 @@ -88,6 +89,8 @@ require ( github.com/subosito/gotenv v1.2.0 // indirect github.com/ulikunitz/xz v0.5.11 // indirect github.com/xanzy/ssh-agent v0.2.1 // indirect + github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f // indirect + github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 // indirect golang.org/x/net v0.0.0-20220722155237-a158d28d115b // indirect golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f // indirect gopkg.in/ini.v1 v1.62.0 // indirect diff --git a/go.sum b/go.sum index fefe1ab48bd..f80f605bd59 100644 --- a/go.sum +++ b/go.sum @@ -342,6 +342,12 @@ github.com/ulikunitz/xz v0.5.11 h1:kpFauv27b6ynzBNT/Xy+1k+fK4WswhN/6PN5WhFAGw8= github.com/ulikunitz/xz v0.5.11/go.mod h1:nbz6k7qbPmH4IRqmfOplQw/tblSgqTqBwxkY0oWt/14= github.com/xanzy/ssh-agent v0.2.1 h1:TCbipTQL2JiiCprBWx9frJ2eJlCYT00NmctrHxVAr70= github.com/xanzy/ssh-agent v0.2.1/go.mod h1:mLlQY/MoOhWBj+gOGMQkOeiEvkx+8pJSI+0Bx9h2kr4= +github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f h1:J9EGpcZtP0E/raorCMxlFGSTBrsSlaDGf3jU/qvAE2c= +github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f/go.mod h1:N2zxlSyiKSe5eX1tZViRH5QA0qijqEDrYZiPEAiq3wU= +github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 h1:EzJWgHovont7NscjpAxXsDA8S8BMYve8Y5+7cuRE7R0= +github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415/go.mod h1:GwrjFmJcFw6At/Gs6z4yjiIwzuJ1/+UwLxMQDVQXShQ= +github.com/xeipuuv/gojsonschema v1.2.0 h1:LhYJRs+L4fBtjZUfuSZIKGeVu0QRy8e5Xi7D17UxZ74= +github.com/xeipuuv/gojsonschema v1.2.0/go.mod h1:anYRn/JVcOK2ZgGU+IjEV4nwlhoK5sQluxsYJ78Id3Y= github.com/yuin/goldmark v1.1.25/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74= github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74= github.com/yuin/goldmark v1.1.32/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=