Delete the library, build again

This is the step the language exists for. Everything else in iyi, the pub signatures, the traits, the orphan rule, is here to make it hold.

Two files are enough to show it, so start with the one being imported. Every iyi file opens by naming its compilation unit, and that name is absolute. It tells you where the file sits: a module called app/greeter lives at app/greeter.iyi, resolved from the project root and never relative to whoever imports it. No manifest, no include path, no search order.

# A module other files can import. See `../modules.iyi`.
#
# R-1: the module path is the compilation unit's name, and it is absolute —
# resolved from the project root, never relative to whoever imports it. That
# is what makes `app/greeter` mean the same module in every file that writes
# it. The file lives at `app/greeter.iyi` because the path says so.
module app/greeter

pub trait Greet
  abstract def greet : String
end

pub def polite(name : String) : String
  "#{greeting}, #{name}."
end

# R-2: not exported, so this is the module's own business. `modules.iyi` can
# neither `import app/greeter::{greeting}` nor reach it by any other route —
# `.iyimod` carries a module's exports and nothing else, so a name left
# unmarked has to be unreachable or that metadata would not be enough to
# compile against (SPEC.md IV.2).
def greeting : String
  "Hello"
end

# Also exported, and deliberately named the same as something in
# `app/formal` — see how `modules.iyi` has to deal with that.
pub def title : String
  "friend"
end

polite and title carry pub and greeting does not, which is the next step's subject. What matters here is the other half of that file: the signatures, and not the bodies underneath them.

Now build a consumer of it once, keeping each module's artifact. Then delete the library and build again.

$ iyi build --emit-iyimod mods -o hello main.iyi
$ rm -r app                                     # the library, gone
$ iyi build --use-iyimod mods -o hello main.iyi
$ ./hello
Hello, world.

Look at the rm -r app line, then at what the program printed. The library's source is gone. The build works anyway, and the binary it produced runs.

Nothing was cached. The second build never opens polite's body, because there is no body on the disk to open. It reads mods/app/greeter.iyimod, which carries the declarations it type checks against and the machine code it links. README.md puts it in one sentence in the paragraph under that block: a module compiles against what its imports say, not against what they do.

That is R-1, and this is what it buys. Everything after this step is the bill.

Try it on the samples#

The repository does not ask you to take this on faith, and the sample carries the procedure in its own comments.

# Compiling this file without `app/greeter.iyi`
# ---------------------------------------------------------------------------
#
# R-1 says a module that imports another reads its `.iyimod` and never opens
# its source. That is not a claim about a future release:
#
#     ./bin/crystal build --no-codegen --emit-iyimod /tmp/mods samples/iyi/modules.iyi
#     ./bin/crystal mod dump --declarations /tmp/mods/app/greeter.iyimod
#     mv samples/iyi/app /tmp/app-elsewhere
#     ./bin/crystal build --no-codegen --use-iyimod /tmp/mods samples/iyi/modules.iyi   # compiles
#     mv /tmp/app-elsewhere samples/iyi/app
#
# The second command prints what the third one compiles against: `app/greeter`
# with `pub def polite(name : String) : String`, `pub trait Greet` with its
# requirement, and no bodies at all. `greeting` is not in it — it carries no
# `pub`, and R-2b's "unreachable rather than absent from an import's names"
# is the same statement as "not in the artifact".

The middle command is the one to run first. mod dump --declarations prints exactly what the artifact only build gets to see: app/greeter with pub def polite(name : String) : String, pub trait Greet with its requirement, and no bodies at all. greeting is missing from it, because it never carried pub.

The same move on a framework#

Two files is a demonstration. A web framework is a test.

$ iyi build --emit-iyimod mods samples/iyi/webapp.iyi   # writes kemal/router.iyimod, ...
$ rm -rf samples/iyi/kemal                              # the library's source, gone
$ iyi build --use-iyimod mods samples/iyi/webapp.iyi    # builds, links, runs, same output

samples/iyi/webapp.iyi is a port of Kemal onto iyi's rules, and its router lives in samples/iyi/kemal. That whole directory goes away between the two builds, and the program still builds, links, runs, and prints the same output.

The roundtrip gate#

bench/samples_roundtrip.sh is where the claim stops being prose. For every sample that imports a module it builds with --emit-iyimod, runs the binary, and keeps what it printed. Then it deletes app, std, boot and kemal, so a build that wants a module's source has nothing to fall back on. Then it builds each sample again with --use-iyimod, runs that second binary, and diffs the two outputs. Any sample that fails to build either way, or prints something different, exits the script non zero. README.md says CI runs it on every push.

Look at what the diff compares: that both programs ran, and printed the same thing. Merely checking that both builds succeeded would only prove the front end swallowed the artifacts. The script's own header is blunt about why the whole test: the only way to be sure a consumer never reads a dependency's source is to take the source away and see whether the build still produces a program that behaves.

What that boundary saves in seconds belongs to a machine rather than to a language, so this page will not quote you a number. README.md publishes them with the machine attached and the command that measures them.

Acyclic imports#

The rule that import forms a DAG is enforced long before any of that, and it has to be: a module initializes after every module it imports, so two modules that wait for each other have no order to be initialized in and there is no build to have.

Write one anyway and the compiler declines, draws the cycle it found, and names the move that fixes it.