polar

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.List imports the module under its last name, so you write List.map.
  • Money as M picks a different name, so you write M.add.
  • Std.Prelude { show } also brings trait methods into scope, so you can call show(x) without a prefix.
  • Ticket.{Conn, Response} is a module group. It is the same as writing Ticket.Conn and Ticket.Response on 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 Money loads src/money.px, which declares module 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.