Skip to content

create-julia-distribution.md

Latest commit

 

History

History
86 lines (66 loc) · 4.55 KB

create-julia-distribution.md

File metadata and controls

86 lines (66 loc) · 4.55 KB
Raw

create-julia-distribution

Builds a relocatable Julia distribution from a project.

- name: "Create the Julia distribution"
  id: "build-distribution"
  uses: "JuliaComputing/create-julia-distribution@958799562b82fcabd2f5508f7ee296e1d91de200"
  with:
    distribution-id: "my-distribution"

Inputs

Input Required Default Description
additional-copy-globs no — Newline-separated glob patterns, relative to each package root, of files to copy into the distribution on top of the ones always copied. See what is always copied and the limits of this input.
compress-sysimage no false Whether to compress the system image heap using zstd, trading load time for size. Requires Julia 1.13+.
distribution-id yes — The identifier of the distribution, which names the directory it is written to.
precompile-execution-file no precompile.jl Julia code to run as the precompilation workload while the system image is built, absolute or relative to source-path. See the precompilation workload.
source-path no ${{ github.workspace }} The project to build the distribution from, and what a relative precompile-execution-file or sysimage-script resolves against. The copy globs resolve against each package root instead.
sysimage-script no — Julia file to execute while the system image is generated, absolute or relative to source-path. See the system image script.

Outputs

Output Description
distribution-path Absolute path of the unpacked distribution directory that was built, in the runner's native path convention.

The path follows the inputs rather than the build: it is <source-path>/distributions/<distribution-id>. Consume the output rather than restating that convention.

The project it builds from

source-path needs to hold a Project.toml. A Manifest.toml beside it is not required, but is strongly advised: without one the build resolves its own, so the versions that end up in the distribution — transitive dependencies included — are decided at build time rather than by you. Committing one is what makes two builds of the same commit produce the same distribution.

The dependencies have to be resolvable by the time the action runs — see bring your own registries and credentials.

What is always copied

Baking a package into the system image is not the same as shipping its files, and some of those files are needed at run time. Every package in the project's manifest contributes:

  • src/** and ext/** — sources, and the extensions of precompiled packages.
  • license*, copying*, changelog* and news* in the package root, matched case-insensitively. Retaining license files tends to be a condition of shipping the package at all.
  • Artifacts.toml — read whenever an artifact is resolved, which matters to whoever builds a further system image on top of the distribution.
  • README.md — read while some packages are evaluated, and worth shipping beside the sources regardless.

additional-copy-globs adds to that list rather than replacing it.

The precompilation workload

precompile-execution-file names Julia code executed while the system image is built, so that what it exercises is compiled into the image. It corresponds to PackageCompiler's precompile_execution_file.

It defaults to precompile.jl in the root of source-path, and a project without that file builds without a workload and without complaint. Naming a file that does not exist warns rather than fails, so a typo shows up in the log rather than halting a long build.

The system image script

sysimage-script names Julia code executed while the system image is generated, corresponding to PackageCompiler's script. Use it for what has to be baked into the image rather than applied to the tree afterwards — rewriting what the runtime reports about itself, for instance. Unlike the precompilation workload, a file that is not there fails the build rather than being skipped.

The action supplies a script of its own regardless, and composes rather than exposes it: the action's runs first and yours after it, never in its place. The action's rewrites the package origin paths baked into the image, so pathof and pkgdir report locations inside the distribution rather than on the machine that built it, as does anything deriving from them.