Module metadata

The build that writes output/<Module>/index.js also writes output/<Module>/metadata.json. For a module named Library.Types, that is output/Library.Types/metadata.json.

Only modules that a build compiled have a record. A module that no build has compiled has no directory, so a missing file means that Iris hasn't compiled the module. The Prim modules never have records.

There is no file that lists every module, so start from the module you want and read its record.

iris build, iris run, iris test, and iris watch write the records beside the modules they compile, in output or in the directory that --output DIR names.

A build with errors writes nothing, so it leaves every earlier record as it was. If a write fails, Iris reports the error, and the module keeps its previous record, or stays without one, until a later build writes it. Iris writes records in parallel, so other records from the same build may already be replaced.

--package NAME limits what Iris compiles to that package and its dependencies, so it writes records only for modules in those packages. Records of other packages stay as they were. With --package, iris watch ignores new files outside the selected packages and their dependencies.

Neither iris build nor iris watch deletes anything in the output directory, so a module directory and its record may be stale: left there by an earlier build. After you delete or rename a module, its directory and its record stay behind, and nothing marks them as stale.

Don't list output to find modules, because that includes stale ones. Start at your entry module and follow its imports through the generated JavaScript instead. To clean up, delete the output directory and build again.

Iris replaces each record atomically. It writes the new record to a temporary file in the module's directory and renames it over metadata.json, so a reader sees either the previous record or the new one, never a partial file. Iris skips a record whose content hasn't changed. The module's other files are written in place, so a reader can see them partially written while a build runs.

iris build and iris watch can write to the same output directory at the same time. Whichever finishes last leaves its records.

Here is the record for a module in a workspace package named library:

{  "version": 1,  "iris": "0.1.8",  "package": "library",  "editable": true,  "source": "/home/user/project/packages/library/src/Library.purs",  "foreign": "foreign.js"}

The record is indented JSON. It has no timestamp or build counter, so the same module and Iris version always produce the same record. Its fields are:

• version is the schema version, currently 1. It only changes when a change could break existing readers, so check it first.
• iris is the version of Iris that wrote the record, as iris --version prints it, including suffixes like 0.1.8-dev.0123abc.
• package is the name of the package that owns the module's source file.
• editable is true for workspace and local packages, and false for registry and git packages.
• source is the absolute path of the PureScript source file, in the platform's native format.
• foreign is the name of the foreign module in the module's output directory, such as foreign.js or foreign.jsx, or null if the module doesn't import foreign values.

The record doesn't list the module's imports. Read them from the generated JavaScript. It also says nothing about diagnostics.

A source file belongs to the package whose source globs match it. A package's globs are src/**/*.purs and test/**/*.purs under its root. Registry, git, and local packages have no test glob. iris watch uses the same rule for files you create while it runs.

A file that two packages match is an error. For example, that happens when one package's root is inside another package's src directory. Two files that declare the same module name are also an error, because they would write the same output files.