Skip to main content

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 std it was built with, which matters since std uses the newest features of the language.
  • The files are read-only: editing them would change std for 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 Support on 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):

  1. BOLT_PRELUDE_PATH, the directory of a std to use instead: the one with __prelude__ in it, like the packages/std of the repository. It's for working on std itself, 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 a std.
  2. In a debug build, made with cargo build without --release, the packages/std of the repository it was built from. So running bolt from the repository, like with cargo run, uses what's being changed, without setting anything.
  3. 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).