Modules and Packages
Every Polar file is a module. Modules are grouped into projects, which you run, and packages, which other projects depend on.
Importing with uses
The uses zone lists the modules a file needs. There are
three forms:
uses
Std.List
Money as M
Std.Prelude { show }
Ticket.{Conn, Response}
-
Std.Listimports the module under its last name, so you writeList.map. -
Money as Mpicks a different name, so you writeM.add. -
Std.Prelude { show }also brings trait methods into scope, so you can callshow(x)without a prefix. -
Ticket.{Conn, Response}is a module group. It is the same as writingTicket.ConnandTicket.Responseon their own lines, and each one is used under its last name.
Where modules come from
-
Paths starting with
Std.come from the standard library. - Paths starting with a dependency's module name come from that package.
-
Everything else comes from your project's
src.uses Moneyloadssrc/money.px, which declaresmodule Money.
Exports
The exports zone lists the functions, constants,
effects, hosts and types that other modules can use. Anything not
listed stays private to the file.
Listing a type exports its cases too, so other modules can build and
match on Circle and Rect. A type you leave
out is private, which is how you keep a representation to yourself.
An exported function, constant or effect can't mention a private
type, because other modules couldn't name it:
error[POLAR0322]: `area` is exported, but it uses the private type `Shape`
--> tour.px:115:3
|
115 | area
| ^^^^
| other modules can't name `Shape`
|
= help: export `Shape` too: add it to `exports`
Types that a zone plugin generates, such as the ones from
schema, are exported automatically. An extern can be
listed in exports directly, so a binding doesn't need a
wrapper function.
Packages
A package is a library: it's checked and depended on, but not run by
itself. Its polar.toml has a
[package] section instead of [project],
and claims one top-level module name:
[package]
name = "simple_framework"
module = "Framework" # claims every `uses Framework.…`
Inside the package, file names leave out the claimed name:
src/html.px is module Html, and everyone
imports it as Framework.Html, including the package's
own files.
Dependencies
Projects and packages list their dependencies by path, or by the address of a git repository:
[dependencies]
simple_framework = { path = "../simple_framework" }
ticket = { git = "github.com/owner/ticket", version = "v0.1.0" }
Paths are relative to the polar.toml. Dependencies
compile into dist/_deps/<package>/, so the build
stays self-contained.
Git dependencies
There is no registry: the repository address is the package's
identity, as in Go. Any git host works, and private repositories use
your own git credentials. A dependency pins exactly one of
version (a tag like v1.2.3),
branch (locked to a commit when you add or update it)
or rev (a full 40-character commit). The key must be
the package's own name.
$ polar add github.com/owner/ticket # newest tag
$ polar add github.com/owner/tool@v1.4.1
$ polar fetch # download what polar.lock names
$ polar update # move to the newest tags
$ polar remove tool
polar.lock pins every package in the whole graph to a
commit and a sha-256 checksum. Commit it. Builds use the lock and
fetch whatever it names when the cache is cold; they never
re-resolve on their own, and a checksum mismatch is an error.
Packages are cached once per commit under
~/.polar/pkg/ (set POLAR_HOME to move it),
and --offline or POLAR_OFFLINE=1 forbids
any network access. Fetching needs git on your
PATH.
When two packages want different versions of one dependency, the
highest requested version wins. It is never newer than something
asked for, so there are no surprise upgrades. A v2 or
later major is a different package: its address ends in
/v2.
The Polar version
A package can say which Polar it was written for:
[package]
name = "ticket"
module = "Ticket"
polar = "0.4.0"
If you import a package written for an older Polar, or one that
needs a newer Polar than yours, polar prints a warning
and carries on. Only the major and minor numbers count, since a
patch release never breaks a package. A package that leaves
polar out is never warned about.
Launchers
Some programs need more than main to start. A web app
built for Browser and Node needs a server
that hands out the browser bundle, answers
bridge calls and runs routes. A package
can provide that as a launcher, a Node script:
# in the package
[launcher]
script = "launcher/serve.mjs"
A project picks a launcher from one of its direct dependencies, and can pass it options:
# in the project
[run]
launcher = "simple_framework"
options = { port = 3000 }
Now polar run builds every host and hands the result to
the launcher. The launcher receives a manifest file describing the
build:
{ "version": 1, "project": "web_posts", "root": "/abs/projects/web_posts",
"out": "/tmp/polar-run-…/dist", "main": "main.js",
"hosts": { "Browser": "/tmp/…/dist/Browser", "Node": "/tmp/…/dist/Node" },
"options": { "port": 3000 } }
polar build bundles the launcher too, so
polar start or node dist/start.mjs runs
the built app without compiling again.
Note: The launcher script is copied on its own, so it can't import files that sit next to it.
Packages can also add new zones to the language. That's the last guide: Zone Plugins.