Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

docs: add App specification #67

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
dido18 wants to merge 10 commits into main
base: main
Choose a base branch
Loading
from app-specification
Draft

docs: add App specification #67

dido18 wants to merge 10 commits into main from app-specification

Conversation

@dido18
Copy link
Contributor

@dido18 dido18 commented Nov 12, 2025
edited by cmaglie
Loading

Motivation

Change description

Additional Notes

Reviewer checklist

  • PR addresses a single concern.
  • PR title and description are properly filled.
  • Changes will be merged in main.
  • Changes are covered by tests.
  • Logging is meaningful in case of troubleshooting.

@per1234 per1234 added documentation Improvements or additions to documentation enhancement New feature or request labels Nov 12, 2025

The `app.yaml` (or `app.yml`) is a YAML file that describes an App.

- `name`: (optional) a short name of the app.
Copy link
Contributor

@mirkoCrobu mirkoCrobu Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the name optional?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've removed the optional piece. Maybe we should just specify what's mandatory, implying that everything else is optional.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or, better, we should provide a JSON SCHEMA file (as we did for the Arduino CLI configuration) https://github.com/arduino/arduino-cli/blob/master/internal/cli/configuration/configuration.schema.json

dido18 reacted with thumbs up emoji
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BTW, currently an empty app.yaml is valid and the ardiuno-app-cli is able to run it.

arduino@merola:~/ArduinoApps/my-app$ cat app.yaml

Comment on lines +94 to +98
### Other

Other sub-folders or files can be added to the app folder.
The reserved folder names are `sketch` and `python`.
The reserved file names are `app.yaml` and `sketch.yaml`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should discourage adding extra files in the root folder; maybe we could reserve an extras folder for user-specific data.

- `name`: A short name of the app.
- `description`: A brief description of the app.
- `icon`: The emoji of the app.
- `ports`: A list of TCP ports to be exposed externally. If not given a random port is opened (if necessary).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does it mean that it opens a "random" port? 🤔 What is this port used for?

- `description`: A brief description of the app.
- `icon`: The emoji of the app.
- `ports`: A list of TCP ports to be exposed externally. If not given a random port is opened (if necessary).
- `bricks`: A list of bricks used by the app with its variable definitions.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's a "brick"? There is an entire session missing that explains what a "brick" is.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@cmaglie cmaglie cmaglie left review comments

@mirkoCrobu mirkoCrobu mirkoCrobu left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

AltStyle によって変換されたページ (->オリジナル) /