Packages
An import whose path doesn't start with ./ or ../, like
import "shapes/circle", names a package. This page is about how the
compiler finds packages, and in particular std, which comes with the
compiler.
Finding a package
A package is a directory with a bolt.toml (boltlang_hir_def::manifest):
[package]
name = "shapes-demo"
prelude = "std" # the default; `false` for none, or a dependency
[dependencies]
shapes = { path = "../shapes" }
A file is in the package of the nearest bolt.toml in its directory or one
of its parents (package_manifest); a file without one is in no package.
import "shapes/circle" is circle.bolt in the directory of the
dependency shapes of the importer's package (resolve_import_path),
which must have a bolt.toml of its own, with its own dependencies. So a
package uses only what it lists, and a dependency's dependencies are its
own business.
Every file is reached by its real path, with symbolic links resolved
(Files::resolve), and a package is its real directory (package_of), so
a file is one file, and in one package, however it's reached: by an
import, as an argument of bolt check, or as a document the editor opens
through a link. The
language server reports a document's errors under the path it was opened
with. pub(package) items are visible in the files of the same package.
std is the exception: it's not a dependency, and every file can use it,
from the compiler (Settings::std_dir in boltlang-base-db). Its files
are the package std, by their path or their real one, and get no
prelude.
A package's prelude is std's, or what its bolt.toml says
(prelude_package), unless bolt check --no-prelude turns it off.
A bolt.toml that can't be read, or says something wrong, like a
dependency called std, is reported (E0113) where the error is in it
(manifest_problems), and so is a dependency whose directory has no
bolt.toml, at its path. The language server shows these in the
bolt.toml: when it's open, and otherwise in the report of the files that
open documents use, with one warning. bolt check, which only checks Bolt
files, reports a bolt.toml that can't be read at the start of each file
of its package, with a label where the error is, and a dependency that
isn't a package where it's imported.
The std that comes with the compiler
The files of packages/std are part of the compiler's binaries
(boltlang-std, whose build script embeds them). So that users can read
them, and an editor open them, the compiler writes them out the first time
it runs, as ordinary files:
~/.local/share/bolt/0.2.0-18bd2315615a79c2/std
- The directory is for this version of the compiler, and a hash of the
files, which says when they changed within a version, as while working
on the compiler. So a compiler always uses the
stdit was built with, which matters sincestduses the newest features of the language. - The files are read-only: editing them would change
stdfor every program, without anyone knowing. - They're written next to the directory first, then moved in place, so that a compiler that stops halfway, or another one at the same time, never leaves part of them.
- It's
$XDG_DATA_HOME, or~/.local/share, on Linux and other Unix systems,~/Library/Application Supporton macOS, and%LOCALAPPDATA%on Windows.
bolt --version shows which std is in use, and where it's from.
Working on std
Which std the compiler uses (boltlang_std::locate):
BOLT_PRELUDE_PATH, the directory of astdto use instead: the one with__prelude__in it, like thepackages/stdof the repository. It's for working onstditself, so that whatever runs, a loose file or another project, uses the copy being changed. If it isn't a directory, the compiler says so and goes on without astd.- In a debug build, made with
cargo buildwithout--release, thepackages/stdof the repository it was built from. So runningboltfrom the repository, like withcargo run, uses what's being changed, without setting anything. - The copy that comes with the compiler, written out as above.
A release build carries the std it was built from, and Cargo builds it
again when a file of packages/std changes. The tests don't use any of
these: TestDb::add_std gives them the repository's std in memory.
The language servers
The language server on the desktop finds std the same way, when it
starts. The one in the browser has no files of its own: the page gives it
the files of std, and says where they are with the initialization option
{ "std": "/std" }, as the playground does.
What's next
Versions of dependencies, a lock file, and a cache of packages in the home directory that the lock file points into, for packages that aren't next to the project (#99).