| name | setup-julia |
| user-invocable | false |
| description | Use when Julia is missing, wrong-version, uninstantiated, or mirror-misconfigured — symptoms like `julia: command not found`, missing `julia-env/Manifest.toml`, package downloads timing out, fresh cluster account, fresh laptop, package-mirror change, or Julia-version bump. |
setup-julia
Install and configure Julia for the harness — install via juliaup, configure the package mirror (defaults to Chinese mirror if region == mainland_china in the cluster profile), and instantiate the project env (julia-env/). Generic over target (local or remote ssh alias). Idempotent — re-running is safe and quick.
Idempotence is enforced, not aspirational:
- (a) Probe MUST succeed before any install attempt — step 3 short-circuits when `julia` is already at the requested version.
- (b) Mirror config replaces (NEVER appends) the `JULIA_PKG_SERVER` line in `startup.jl` and the matching lines in shell rc files.
- (c) `Pkg.instantiate()` is safe to re-run; subsequent runs no-op on already-resolved manifests.
- (d) `verify` MUST pass on the no-op path (re-running the whole workflow on an already-set-up host exits 0 without modifying anything).
This skill is for Julia-specific configuration. Cluster-side conventions (ssh, scheduler, partitions) live in skills/using-slurm/profiles/<active>.toml and are read here for region defaults and (when target is remote) the ssh alias and repo_path_remote.
Julia package stacks are declared separately in skills/<stack>/stack.toml.
This skill only makes Julia itself and julia-env/ usable locally or remotely;
after that, the selected stack's install command (for example make install itensors,
make install sse, or make install pepskit) installs method packages.
When to activate
- A workflow about to run Julia code finds
julia not installed.
- A fresh laptop / fresh cluster account needs the harness's Julia stack.
- Package mirror changes (e.g., the user moves region or the institutional mirror updates).
- Bumping Julia version (
--version 1.11.x).
/using-slurm's pre-submit check sees julia-env/Manifest.toml not yet instantiated on the cluster.
Inputs
| flag | type | default | source-of-default |
|---|
--target | local | remote:<alias> | local | CLI; for remote, <alias> matches skills/using-slurm/profiles/<active>.toml's connection.ssh.alias field; the skill reads repo_path_remote for where the project lives. |
--region | name | from cluster profile's region field | See Mirror reference. |
--mirror | URL | unset | Advanced override for JULIA_PKG_SERVER. |
--version | X.Y.Z | release | release | juliaup's stable channel. When release, the project's julia_version is also consulted. |
--instantiate / --no-instantiate | flag | --instantiate | Runs Pkg.instantiate() after install. |
Recognized regions for --region (see Mirror reference for the contract):
| region | JULIAUP_SERVER | JULIA_PKG_SERVER | source |
|---|
mainland_china | https://mirror.nju.edu.cn/julia-releases/ | https://mirrors.nju.edu.cn/julia | Jinguo guide (Nanjing University mirror) |
| other / unset | unset | unset | Julia defaults (no mirror config) |
Workflow
This skill follows the Jinguo-group recipe verbatim (https://book.jinguo-group.science/stable/chap2/julia-setup/). Mirror first, then install — juliaup itself respects JULIAUP_SERVER if exported before the curl installer runs.
-
Probe target: detect if julia is reachable (PATH, module load, or ~/.juliaup/bin/julia). For remote: ssh <alias> 'command -v julia || command -v juliaup'. Also read the manifest's julia_version to verify version compatibility against any pre-existing Julia.
-
Configure mirror first (only if --region resolves to a mirror): scripts/setup-julia.sh mirror --region <name>. This step runs BEFORE installing Julia even though the Jinguo guide numbers it "Step 2" — the mirror env var MUST be exported before the curl installer fetches juliaup. See Mirror reference for region defaults and URLs.
The script writes BOTH JULIAUP_SERVER and JULIA_PKG_SERVER env vars to every shell rc the script detects (any of ~/.bashrc, ~/.zshrc, ~/.profile); idempotently replaces any prior JULIAUP_SERVER= / JULIA_PKG_SERVER= line. Login-shell user ($SHELL) is ALSO written to ~/.profile to cover non-interactive ssh. AND writes JULIA_PKG_SERVER to ~/.julia/config/startup.jl for julia subprocesses.
Precedence note: shell-rc env var beats startup.jl for julia subprocesses launched in interactive shells; startup.jl beats nothing for julia subprocesses launched without env (e.g., julia invoked from a Slurm script). Both are rewritten on every mirror invocation so they cannot drift.
-
Install Julia. Skip if step 1's probe found a working julia whose julia --version matches --version (or matches the project's julia_version when --version release). Otherwise: scripts/setup-julia.sh install [--region <name>] [--version X.Y.Z].
The script exports `JULIAUP_SERVER` for the current shell (so the curl installer downloads through the mirror); runs `curl -fsSL https://install.julialang.org | sh` to install juliaup; writes the guide's Revise try/catch snippet to `~/.julia/config/startup.jl`; and `Pkg.add("Revise")` into the default env.
The skill verifies AFTER the script returns — all binary, ALL MUST pass:
- (a) `julia --version` reports the requested version (or matches the project's `julia_version` when `--version release`).
- (b) `~/.julia/config/startup.jl` contains the `JULIA_PKG_SERVER` mirror line (when a mirror region was set).
- (c) `julia -e 'using Revise'` exits 0.
-
Instantiate. Local: scripts/setup-julia.sh instantiate <project_dir> (runs Pkg.instantiate(); Pkg.precompile() inside <project_dir>). Remote: same via ssh <alias> 'cd <repo_path_remote> && scripts/setup-julia.sh instantiate julia-env'.
-
Verify: scripts/setup-julia.sh verify <project_dir> <package_name> — three binary items, ALL MUST exit 0:
- (a) `julia --project= -e 'using Pkg; Pkg.status()'` exits 0.
- (b) `julia --project= -e 'using '` exits 0.
- (c) Reported version of `` matches the `Project.toml` compat bound.
-
Hand back: Julia version, mirror url, project env state. Hand-back report per AGENTS.md → Output norms.
Output
- For local: Julia installed and on
$PATH; ~/.julia/config/startup.jl configured; julia-env/ instantiated and precompiled.
- For remote: same, on
<alias>:<repo_path_remote>.
- Hand-back report per AGENTS.md → Output norms.
Composition
Callers (who calls /setup-julia):
/onboard — if the user signals they will write Julia code (e.g., DMRG / ITensors workflows)./using-slurm — pre-submit when the remote cluster's julia-env/Manifest.toml hasn't been instantiated yet.make install julia and make install itensors recipes (the makefile recipes can dispatch the skill via ${CLAUDE_SKILL_DIR}/setup-julia/... once registered).
Downstream (what runs after /setup-julia):
- Any
language = "julia" stack contract in skills/<stack>/stack.toml — /setup-julia precedes the stack's install command.
Data dependencies (what /setup-julia reads):
skills/using-slurm/profiles/<active>.toml — for the region default mirror and (for remote) the ssh alias and repo_path_remote.
Mirror reference
Single source of truth for region → mirror mapping and mirror-config semantics. The Inputs table, step 2, and Anti-patterns all link here.
For users in mainland China, package downloads from pkg.julialang.org are typically slow or unreliable. The Jinguo-group setup guide (https://book.jinguo-group.science/stable/chap2/julia-setup/) configures two mirror env vars, both pointing at Nanjing University:
export JULIAUP_SERVER=https://mirror.nju.edu.cn/julia-releases/
export JULIA_PKG_SERVER=https://mirrors.nju.edu.cn/julia
JULIAUP_SERVER matters for the initial Julia install — without it, juliaup downloads from AWS S3 (slow from mainland China). JULIA_PKG_SERVER matters for every subsequent Pkg.add / Pkg.instantiate. The mirror MUST be set before invoking the curl installer; this skill orders step 2 before step 3 when --region mainland_china.
This skill applies the NJU mirror automatically when the cluster profile's region field is mainland_china. For other regions, no mirror is set. For an institutional mirror, pass --mirror <url> to override JULIA_PKG_SERVER.
Manifest policy
- Rule.
julia-env/Project.toml is committed (the dependency contract); julia-env/Manifest.toml is gitignored and regenerated per machine on first Pkg.resolve() + Pkg.instantiate().
- Reason. Manifests are pinned to a specific
julia_version and don't port across Julia major versions, so committing one would break cross-machine setup.
- Trade-off. Exact dependency-version reproducibility is sacrificed for cross-platform / version portability — acceptable for a research harness running across laptop + cluster + colleagues' machines.
Notes
- Both module-loaded Julia (
module load julia/1.10.9) and juliaup-installed Julia are supported. Default: juliaup — user-controlled Julia version makes Project.toml compatibility easier across laptop + cluster + collaborators. Use module-loaded Julia ONLY when the admin enforces it or the cluster blocks user binaries.
- This skill does NOT do cluster-level setup (ssh keys, scheduler config, account setup). That's
/onboard's cluster-setup stage and the cluster profile's bootstrap_one_time.
Anti-patterns (auto-reject)
- Hardcoding a Chinese mirror for every install — only when `region == mainland_china` (or `--mirror` explicit). See [Mirror reference](#mirror-reference).
- Reinstalling Julia when it's already on `$PATH` and at the requested version — be idempotent.
- Editing `~/.julia/config/startup.jl` destructively — preserve unrelated lines, replace ONLY the `JULIA_PKG_SERVER` line.
- Committing `julia-env/Manifest.toml` to the repo — see [Manifest policy](#manifest-policy).
- Bundling cluster bootstrap (clone repo, module load, etc.) into this skill — that's `/onboard` + `bootstrap_one_time`.
# rewrite ~/.julia/config/startup.jl entirely with just the mirror line
echo 'ENV["JULIA_PKG_SERVER"] = "https://mirrors.nju.edu.cn/julia"' > ~/.julia/config/startup.jl
# replace ONLY the JULIA_PKG_SERVER line; preserve Revise's try/catch and any user content
# (sed -i.bak is portable across BSD/macOS and GNU/Linux; we remove the backup afterwards)
sed -i.bak '/^ENV\["JULIA_PKG_SERVER"\]/d' ~/.julia/config/startup.jl
echo 'ENV["JULIA_PKG_SERVER"] = "https://mirrors.nju.edu.cn/julia"' >> ~/.julia/config/startup.jl
rm -f ~/.julia/config/startup.jl.bak
