118 lines
3.9 KiB
Markdown
118 lines
3.9 KiB
Markdown
# Claro v1.18.26 - Packages and Projects
|
|
|
|
Claro v1.18.26 makes projects and packages safer and more useful while keeping the beginner syntax simple.
|
|
|
|
## Create a project
|
|
|
|
```bash
|
|
claro new MyProject
|
|
cd MyProject
|
|
claro run
|
|
```
|
|
|
|
A new project contains:
|
|
|
|
```text
|
|
main.claro
|
|
claro.project
|
|
claro.lock
|
|
packages/
|
|
README.md
|
|
```
|
|
|
|
## Project file
|
|
|
|
`claro.project` is intentionally plain text:
|
|
|
|
```text
|
|
manifest-version: 1
|
|
name: MyProject
|
|
main: main.claro
|
|
version: v1.18.26
|
|
packages:
|
|
package: text
|
|
package: net_tools
|
|
```
|
|
|
|
## Package commands
|
|
|
|
```bash
|
|
claro package init
|
|
claro package add text
|
|
claro package remove text
|
|
claro package list
|
|
claro package doctor
|
|
claro package lock
|
|
```
|
|
|
|
`claro package add NAME` creates a local folder:
|
|
|
|
```text
|
|
packages/NAME/
|
|
claro.package
|
|
README.md
|
|
```
|
|
|
|
Each `claro.package` file includes a tiny manifest and checksum:
|
|
|
|
```text
|
|
manifest-version: 1
|
|
name: text
|
|
version: 1
|
|
source: local
|
|
checksum: 1234abcd
|
|
```
|
|
|
|
`claro.lock` records the release version, lock format, packages, and checksums so future registry work has a stable safety foundation. `claro package doctor` checks those lockfile checksums for listed packages and reports `BAD lock checksum: name` if the lockfile is stale or edited incorrectly. It also reports `BAD lock package not in claro.project: name` when the lockfile contains a package entry that is not listed in `claro.project`, so learners know to refresh the lockfile instead of trusting stale package data. The project file must declare the complete supported `manifest-version: 1` value; a prefix such as `manifest-version: 10` is rejected as `BAD project manifest version: expected 1`. Package manifests must declare the complete supported `manifest-version: 1` value; a prefix such as `manifest-version: 10` is treated as a missing/unsupported manifest. They must also declare the complete expected `name:` value; a name that only starts with the package name is rejected as `BAD package manifest name: name`. The complete manifest `checksum:` value is checked too, so trailing or extra checksum text is rejected as `BAD package checksum: name`. Package manifests must also declare the complete supported local `version: 1` value and `source: local` value. Prefixes such as `version: 10` and `source: local-extra` are rejected as `BAD package version: name` and `BAD package source: name` rather than being accepted as valid local manifests.
|
|
|
|
## Project-name safety
|
|
|
|
`claro new NAME` checks the project name before creating folders. Project names may use only letters, numbers, dash, and underscore, and they must be 64 characters or fewer.
|
|
|
|
This keeps mistakes like `../bad` from creating a project outside the folder where the learner is working.
|
|
|
|
## Package-name safety
|
|
|
|
Package names may use only:
|
|
|
|
```text
|
|
letters
|
|
numbers
|
|
dash
|
|
underscore
|
|
```
|
|
|
|
Package names must be 64 characters or fewer so Claro can create predictable local package folders and metadata paths.
|
|
|
|
This means simple names like these are allowed:
|
|
|
|
```text
|
|
text
|
|
sdl
|
|
net_tools
|
|
my-package
|
|
```
|
|
|
|
Unsafe names are rejected:
|
|
|
|
```text
|
|
../bad
|
|
folder/name
|
|
bad name
|
|
```
|
|
|
|
If an unsafe package name somehow gets into `claro.project`, package maintenance commands should not quietly continue. `claro package doctor` points out the bad name, `claro package lock` refuses to write lockfile data for it, `claro package list` refuses to display it as a normal package, `claro package init` refuses to report the project ready while the unsafe entry remains, and `claro package remove NAME` exits with an error if the lockfile refresh still sees an unsafe package name after the removal. Learners can still recover by removing the exact unsafe entry, such as `claro package remove ../bad`; Claro rewrites the project file and lockfile without using that unsafe name as a folder path.
|
|
|
|
## Why this matters
|
|
|
|
Packages are important for Claro's future, but the workflow must stay friendly:
|
|
|
|
```text
|
|
make a project
|
|
add a package
|
|
run the project
|
|
check the project
|
|
```
|
|
|
|
No complicated setup should be needed for a beginner.
|