Using packages¶
A package is a directory of stone modules with a stone.toml that names it. A program uses other
people’s packages by naming them in its own stone.toml, next to its entry file. stone downloads
them from GitHub or GitLab releases, so there is no registry to sign up for: any repository whose
releases hold a stone package is one.
Adding a package¶
In your program’s directory (a project that stone init made, or any directory with a
main.stn, or one inside it), run
stone add github:alice/stone-csv
This finds the newest release of alice/stone-csv, downloads it, and writes the dependency to
stone.toml, making the file if there is none:
[dependencies]
csv = { github = "alice/stone-csv", version = "1.4.0" }
The key, csv, is the name the package gives itself, and the name your files use it under.
--name picks another (stone add github:alice/stone-csv --name sheet). The package can be named
in several ways:
you write |
you get |
|---|---|
|
the newest release |
|
the newest 1.2.x release |
|
exactly 1.2.3 |
|
the same as |
|
a project on gitlab.com |
|
a project on your own GitLab |
|
a repository on GitHub Enterprise |
@latest is the default, and it skips pre-releases such as 2.0.0-beta.1. To use one, give it
exactly.
Using it in code¶
A package’s modules are named by the dependency’s name, then their path in the package:
use csv // the package's lib.stn
use csv.encode // encode.stn, or the pub fn encode of lib.stn
use csv.parse.value // parse/value.stn, or the pub fn value of parse.stn
print(csv.decode("a,b"))
use csv loads the package’s lib.stn, the module a package keeps its main functions in. A
package’s files see only their own modules and their own dependencies, never your program’s, so
two packages can each have a util.stn without meaning the same module.
Everything else works as with your own modules: only pub functions and types can be used, and
unused functions are never compiled in. See Modules.
Packages in a directory¶
A dependency can also be a directory, for a package you are writing yourself or one that lives next to your program in the same repository:
[dependencies]
geo = { path = "../geo" }
The path is relative to the stone.toml, and the directory must have a stone.toml of its own
that gives the package a name. stone uses the directory as it is, so a change there shows up the
next time you run. Directories have no versions and are never downloaded or locked.
How versions are chosen¶
Each dependency gives the oldest version it works with, and that is all a manifest ever says about versions. stone uses the newest of the versions that your program and the packages it uses ask for, which is how Go chooses versions:
Your program asks for
csv1.2.0, andgeoasks forcsv1.3.0, so both getcsv1.3.0.A newer 1.9.0 being released changes nothing, until something asks for it.
So the same manifests always give the same versions, on every machine and on every day, and
nothing is ever upgraded behind your back. To upgrade, ask for the newer version: run
stone add github:alice/stone-csv again, or edit the version in stone.toml.
Versions are semantic versions. A new major version may break the code that
uses it, so 1.x and 2.x are treated as different packages: if one part of your program uses
csv 1.4.0 and another csv 2.1.0, both are linked in, each under its own name, and neither
can see the other. Before 1.0, each minor version is its own: 0.3.x and 0.4.x are different
packages too.
stone.lock¶
The first time a package is downloaded, stone writes a hash of its files to stone.lock, next to
stone.toml:
# written by stone: the hash of what each package downloaded held
[[package]]
name = "csv"
github = "alice/stone-csv"
version = "1.4.0"
hash = "sha256:4f1c..."
The lockfile does not choose versions, since the manifests already do. It makes sure that a
package is the same code every time: if a release is later moved to other code, or a file in the
download is changed, the program fails to build. If you trust the change (say, the author fixed a
release on purpose), delete the package’s entry from stone.lock, and the next build records the
new hash. Commit stone.lock, so everyone who builds your program checks against the same
hashes.
Downloading¶
stone run, stone build, and stone check download whatever the program uses that is not
downloaded yet, so after cloning a program, running it is enough. The commands for managing
packages are:
stone fetchdownloads everything the program uses and bringsstone.lockup to date. With--lockedit fails instead ifstone.lockwould change, which is what CI should run.stone treeshows each package the program uses and the packages they use:app └── csv 1.4.0 (github:alice/stone-csv) └── num 0.3.0 (github:bob/num)stone remove csvtakes a dependency out ofstone.toml, and out ofstone.lockwith any package only it used.--offline, given torun,build, orcheck, uses only what is already downloaded and never connects to anything.
Downloaded packages are kept in one place for every program, the package store:
~/.stone/packages, or %LOCALAPPDATA%\stone\packages on Windows. Set STONE_HOME to keep them
in $STONE_HOME/packages instead. Each version of each package is downloaded once, and only its
stone.toml and .stn files are kept. Don’t change files in the store, since they no longer
match stone.lock once changed.
For a private repository, or to avoid GitHub’s limit on requests without a token, set
GITHUB_TOKEN (or GITLAB_TOKEN) to a token that can read it.
Release builds of stone can download. A build from source needs the fetch feature for that
(cargo install --git https://github.com/tarolling/stone --features fetch stone), and without it reads only packages already downloaded.
In the editor¶
The language server reads packages as the compiler does, from the store and from directories, but
never downloads. If a package is not downloaded yet, each use of it shows the error with the
hint to run stone fetch, and so does the dependency in stone.toml. Once stone fetch is done,
the errors clear on their own. Go to definition opens a package’s files, and a package’s names
cannot be renamed from your program, since other programs use them too.
See Publishing a package to make a package of your own, and stone.toml for every
key stone.toml can hold.