mirror of
https://github.com/nim-lang/Nim.git
synced 2026-09-02 03:43:41 +00:00
275 lines
34 KiB
HTML
275 lines
34 KiB
HTML
<?xml version="1.0" encoding="utf-8" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<!-- This file is generated by Nim. -->
|
|
<html xmlns="https://www.w3.org/1999/xhtml" xml:lang="en" lang="en" data-theme="auto">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>doc/atlas</title>
|
|
|
|
<!-- Google fonts -->
|
|
<link href='https://fonts.googleapis.com/css?family=Lato:400,600,900' rel='stylesheet' type='text/css'/>
|
|
<link href='https://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>
|
|
|
|
<!-- Favicon -->
|
|
<link rel="shortcut icon" href="data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAUAAAAF////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAIAAABbAAAAlQAAAKIAAACbAAAAmwAAAKIAAACVAAAAWwAAAAL///8A////AP///wD///8A////AAAAABQAAADAAAAAYwAAAA3///8A////AP///wD///8AAAAADQAAAGMAAADAAAAAFP///wD///8A////AP///wAAAACdAAAAOv///wD///8A////AP///wD///8A////AP///wD///8AAAAAOgAAAJ3///8A////AP///wAAAAAnAAAAcP///wAAAAAoAAAASv///wD///8A////AP///wAAAABKAAAAKP///wAAAABwAAAAJ////wD///8AAAAAgQAAABwAAACIAAAAkAAAAJMAAACtAAAAFQAAABUAAACtAAAAkwAAAJAAAACIAAAAHAAAAIH///8A////AAAAAKQAAACrAAAAaP///wD///8AAAAARQAAANIAAADSAAAARf///wD///8AAAAAaAAAAKsAAACk////AAAAADMAAACcAAAAnQAAABj///8A////AP///wAAAAAYAAAAGP///wD///8A////AAAAABgAAACdAAAAnAAAADMAAAB1AAAAwwAAAP8AAADpAAAAsQAAAE4AAAAb////AP///wAAAAAbAAAATgAAALEAAADpAAAA/wAAAMMAAAB1AAAAtwAAAOkAAAD/AAAA/wAAAP8AAADvAAAA3gAAAN4AAADeAAAA3gAAAO8AAAD/AAAA/wAAAP8AAADpAAAAtwAAAGUAAAA/AAAA3wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAADfAAAAPwAAAGX///8A////AAAAAEgAAADtAAAAvwAAAL0AAADGAAAA7wAAAO8AAADGAAAAvQAAAL8AAADtAAAASP///wD///8A////AP///wD///8AAAAAO////wD///8A////AAAAAIcAAACH////AP///wD///8AAAAAO////wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A//8AAP//AAD4HwAA7/cAAN/7AAD//wAAoYUAAJ55AACf+QAAh+EAAAAAAADAAwAA4AcAAP5/AAD//wAA//8AAA=="/>
|
|
<link rel="icon" type="image/png" sizes="32x32" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAA3XAAAN1wFCKJt4AAAAB3RJTUUH4QQQEwksSS9ZWwAAAk1JREFUWMPtll2ITVEUx39nn/O7Y5qR8f05wtCUUr6ZIS++8pEnkZInPImneaCQ5METNdOkeFBKUhMPRIkHKfEuUZSUlGlKPN2TrgfncpvmnntnmlEyq1Z7t89/rf9a6+y99oZxGZf/XeIq61EdtgKXgdXA0xrYAvBjOIF1AI9zvjcC74BSpndrJPkBWDScTF8Aa4E3wDlgHbASaANmVqlcCnwHvgDvgVfAJ+AikAAvgfVZwLnSVZHZaOuKoQi3ZOMi4NkYkpe1p4J7A8BpYAD49hfIy/oqG0+hLomiKP2L5L+1ubn5115S+3OAn4EnwBlgMzCjyt6ZAnQCJ4A7wOs88iRJHvw50HoujuPBoCKwHWiosy8MdfZnAdcHk8dxXFJ3VQbQlCTJvRBCGdRbD4M6uc5glpY3eAihpN5S5w12diSEcCCEcKUO4ljdr15T76ur1FDDLIQQ3qv71EdDOe3Kxj3leRXyk+pxdWnFWod6Wt2bY3de3aSuUHcPBVimHs7mK9WrmeOF6lR1o9qnzskh2ar2qm1qizpfXaPeVGdlmGN5pb09qMxz1Xb1kLqgzn1RyH7JUXW52lr5e/Kqi9qpto7V1atuUzfnARrV7jEib1T76gG2qxdGmXyiekkt1GswPTtek0aBfJp6YySGBfWg2tPQ0FAYgf1stUfdmdcjarbYJEniKIq6gY/Aw+zWHAC+p2labGpqiorFYgGYCEzN7oQdQClN07O1/EfDyGgC0ALMBdYAi4FyK+4H3gLPsxfR1zRNi+NP7nH5J+QntnXe5B5mpfQAAAAASUVORK5CYII=">
|
|
|
|
<!-- CSS -->
|
|
<link rel="stylesheet" type="text/css" href="nimdoc.out.css?v=2.3.1">
|
|
|
|
<!-- JS -->
|
|
<script type="text/javascript" src="dochack.js?v=2.3.1"></script>
|
|
</head>
|
|
<body>
|
|
<div class="document" id="documentId">
|
|
<input type="checkbox" id="nav-toggle" hidden>
|
|
<label for="nav-toggle" id="nav-burger">☰</label>
|
|
<label for="nav-toggle" id="nav-overlay"></label>
|
|
<div class="container">
|
|
<h1 class="title">doc/atlas</h1>
|
|
|
|
<h1 id="atlas-package-cloner">Atlas Package Cloner</h1><p>Atlas is a simple package cloner tool. It manages project dependencies in an isolated <tt class="docutils literal"><span class="pre">deps/</span></tt> directory.</p>
|
|
<p>Atlas is compatible with Nimble in the sense that it supports the Nimble file format.</p>
|
|
|
|
<h2 id="concepts">Concepts</h2><p>Atlas uses two main concepts:</p>
|
|
<ol class="simple"><li>Projects</li>
|
|
<li>Dependencies</li>
|
|
</ol>
|
|
|
|
<h3 id="projects">Projects</h3><p>A project is a directory that has a file <tt class="docutils literal"><span class="pre">atlas.config</span></tt> inside it. Use <tt class="docutils literal"><span class="pre">atlas init</span></tt> to create a project out of the current working directory.</p>
|
|
<p>Projects can share dependencies and be developed locally by using the <tt class="docutils literal"><span class="pre">link</span></tt> command. This creates <tt class="docutils literal"><span class="pre">nimble-link</span></tt> files that allow projects to share their dependencies.</p>
|
|
<p>The project structure looks like this:</p>
|
|
<p><pre class="listing"> $project / project.nimble
|
|
$project / nim.cfg
|
|
$project / other main project files...
|
|
$project / deps / atlas.config
|
|
$project / deps / dependency-A
|
|
$project / deps / dependency-B
|
|
$project / deps / dependency-C.nimble-link (for linked projects)</pre></p>
|
|
<p>The deps directory can be set via <tt class="docutils literal"><span class="pre">--deps=DIR</span></tt> during <tt class="docutils literal"><span class="pre">atlas init</span></tt>.</p>
|
|
|
|
<h3 id="dependencies">Dependencies</h3><p>Inside a project there is a <tt class="docutils literal"><span class="pre">deps</span></tt> directory where your dependencies are kept. It is easy to move a dependency one level up and out of the <tt class="docutils literal"><span class="pre">deps</span></tt> directory, turning it into a project. Likewise, you can move a project to the <tt class="docutils literal"><span class="pre">deps</span></tt> directory, turning it into a dependency.</p>
|
|
<p>The only distinction between a project and a dependency is its location. For dependency resolution a project always has a higher priority than a dependency.</p>
|
|
|
|
<h2 id="no-magic">No magic</h2><p>Atlas works by managing two files for you, the <tt class="docutils literal"><span class="pre">project.nimble</span></tt> file and the <tt class="docutils literal"><span class="pre">nim.cfg</span></tt> file. You can edit these manually too, Atlas doesn't touch what should be left untouched.</p>
|
|
|
|
<h2 id="how-it-works">How it works</h2><p>Atlas uses git commits internally; version requirements are translated to git commits via git tags and a fallback of searching Nimble file commits. When Atlas identifies an untagged commit after a Nimble version bump, it shows the number of intervening commits as SemVer build metadata. For example, the fifth commit after version <tt class="docutils literal"><span class="pre">1.2.3</span></tt> is displayed as <tt class="docutils literal"><span class="pre">1.2.3+5@abcdef12</span></tt>. Build metadata does not change SemVer precedence, so it still satisfies requirements for <tt class="docutils literal"><span class="pre">1.2.3</span></tt> while making the checkout's distance from the version bump visible. This display is also used when a <tt class="docutils literal"><span class="pre">#head</span></tt> requirement selects that commit; the resolved version is shown once with a trailing <tt class="docutils literal"><span class="pre">^</span></tt>, rather than as a separate <tt class="docutils literal"><span class="pre">#head</span></tt> release. An explicit commit requirement uses the same nearest-version display and adds <tt class="docutils literal"><span class="pre">[pinned]</span></tt>, for example <tt class="docutils literal"><span class="pre">1.2.3+5@abcdef12 [pinned]</span></tt>. Commit requirements retain their full hashes internally but are shortened to eight characters in version-selection output.</p>
|
|
<p>Atlas uses URLs internally; Nimble package names are translated to URLs via Nimble's <tt class="docutils literal"><span class="pre">packages.json</span></tt> file. Atlas uses "shortnames" for known URLs from packages. Unofficial URLs, including forks, using a name triplet of the form <tt class="docutils literal"><span class="pre">projectName.author.host</span></tt>. For example Atlas would be <tt class="docutils literal"><span class="pre">atlas.nim-lang.github.com</span></tt>. Packages can be added using <tt class="docutils literal"><span class="pre">nameOverrides</span></tt> in <tt class="docutils literal"><span class="pre">atlas.config</span></tt> which adds a new name to URL mapping. Atlas downloads <tt class="docutils literal"><span class="pre">packages.json</span></tt> into <tt class="docutils literal"><span class="pre">deps/_packages</span></tt> by default; pass <tt class="docutils literal"><span class="pre">--packagesRepo</span></tt> to keep the git-clone behavior for the full packages repo. If dependency URLs use <tt class="docutils literal"><span class="pre">git://</span></tt>, pass <tt class="docutils literal"><span class="pre">--forceGitToHttps</span></tt> to rewrite them to <tt class="docutils literal"><span class="pre">https://</span></tt> before cloning.</p>
|
|
<p>Atlas caches parsed dependency release metadata in <tt class="docutils literal"><span class="pre">deps/.cache</span></tt>. Each cache file is scoped to one package URL and is reused only while the package's remote HEAD, local checked-out commit, fetched tag refs, and relevant release-collection flags still match. If those inputs change, Atlas reparses the package's Nimble files and rewrites the cache. This includes a new tag published at an existing commit after <tt class="docutils literal"><span class="pre">atlas install --update</span></tt> fetches it.</p>
|
|
<p>In addition to full URLs and package names, Atlas supports a shorthand <strong>forge alias</strong> syntax of the form <tt class="docutils literal"><span class="pre"><alias>:<user>/<repo></span></tt>. The supported aliases are:</p>
|
|
<table border="1" class="docutils"><tr><th>Alias</th><th>Expands to</th></tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">gh</span></tt> / <tt class="docutils literal"><span class="pre">github</span></tt></td><td><tt class="docutils literal"><span class="pre">https://github.com/<user>/<repo></span></tt></td></tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">gl</span></tt> / <tt class="docutils literal"><span class="pre">gitlab</span></tt></td><td><tt class="docutils literal"><span class="pre">https://gitlab.com/<user>/<repo></span></tt></td></tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">srht</span></tt> / <tt class="docutils literal"><span class="pre">sourcehut</span></tt></td><td><tt class="docutils literal"><span class="pre">https://git.sr.ht/~<user>/<repo></span></tt></td></tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">cb</span></tt> / <tt class="docutils literal"><span class="pre">cberg</span></tt> / <tt class="docutils literal"><span class="pre">codeberg</span></tt></td><td><tt class="docutils literal"><span class="pre">https://codeberg.org/<user>/<repo></span></tt></td></tr>
|
|
</table><p>For example:</p>
|
|
<p><pre class="listing">atlas use gh:zedeus/nitter
|
|
atlas use gl:someuser/somepkg
|
|
atlas use srht:~someuser/somepkg
|
|
atlas use cb:someuser/somepkg</pre></p>
|
|
<p>Forge aliases can also be used in Nimble <tt class="docutils literal"><span class="pre">require</span></tt> statements:</p>
|
|
<p><pre class="listing"><span class="Identifier">require</span> <span class="StringLit">"gh:user/repo"</span>
|
|
<span class="Identifier">require</span> <span class="StringLit">"gl:user/repo >= 1.0"</span></pre></p>
|
|
<p>Atlas does not call the Nim compiler for a build, instead it creates/patches a <tt class="docutils literal"><span class="pre">nim.cfg</span></tt> file for the compiler. For example:</p>
|
|
<p><pre class="listing">############# begin Atlas config section ##########
|
|
--noNimblePath
|
|
--path:"deps/nimx"
|
|
--path:"deps/sdl2/src"
|
|
--path:"deps/opengl/src"
|
|
--path:"../linked-project/src"
|
|
--path:"../linked-project/deps/msgpack4nim/"
|
|
############# end Atlas config section ##########</pre></p>
|
|
<p>The version selection is deterministic, it picks up the <em>minimum</em> required version. Thanks to this design, lock files are much less important.</p>
|
|
|
|
<h2 id="commands">Commands</h2><p>Some commonly used commands:</p>
|
|
|
|
<h3 id="use-lturlgt-slash-ltpackage-namegt-slash-ltforge-aliasgt">Use <url> / <package name> / <forge alias></h3><p>Clone the package behind <tt class="docutils literal"><span class="pre">url</span></tt>, <tt class="docutils literal"><span class="pre">package name</span></tt>, or <tt class="docutils literal"><span class="pre">forge alias</span></tt> and its dependencies into the <tt class="docutils literal"><span class="pre">deps</span></tt> directory and make it available for your current project. Atlas will create or patch the files <tt class="docutils literal"><span class="pre">$project.nimble</span></tt> and <tt class="docutils literal"><span class="pre">nim.cfg</span></tt> for you so that you can simply import the required modules.</p>
|
|
<p>For example:</p>
|
|
<p><pre class="listing"> mkdir newproject
|
|
cd newproject
|
|
git init
|
|
atlas use lexim
|
|
# or using a forge alias:
|
|
atlas use gh:zedeus/nitter
|
|
# add `import lexim` to your example.nim file
|
|
nim c example.nim
|
|
</pre></p>
|
|
|
|
<h3 id="link-ltpathgt">Link <path></h3><p>Link another project into the current project to share its dependencies. This creates <tt class="docutils literal"><span class="pre">nimble-link</span></tt> files that allow the projects to share their dependencies.</p>
|
|
<p>For example:</p>
|
|
<p><pre class="listing"> atlas link ../other-project</pre></p>
|
|
<p>This will link the other project and make its dependencies available to your current project. The other project must be another Atlas project and have a Nimble file. Run <tt class="docutils literal"><span class="pre">atlas install</span></tt> in the linked project first so Atlas can create its current dependency activation cache. This is required when linking projects last installed by an older Atlas version.</p>
|
|
<p>The linked project will be added to this project's Nimble file if it's not already present.</p>
|
|
<p>Note, that the other project's <tt class="docutils literal"><span class="pre">nameOverrides</span></tt> and <tt class="docutils literal"><span class="pre">urlOverrides</span></tt> <em>aren't</em> imported. You may need to import the name-overrides to properly use the deps. This is due to the triplet-naming above.</p>
|
|
|
|
<h3 id="unlink-ltpackagegt">Unlink <package></h3><p>Remove a linked package from the current project, including its <tt class="docutils literal"><span class="pre">nimble-link</span></tt> files, activation-cache entries, and generated <tt class="docutils literal"><span class="pre">nim.cfg</span></tt> paths. By default, Atlas also removes the linked package's cached child dependencies:</p>
|
|
<p><pre class="listing"> atlas unlink other-project</pre></p>
|
|
<p>Children still needed by another active dependency are kept linked.</p>
|
|
<p>Use <tt class="docutils literal"><span class="pre">--only</span></tt> to remove just the named package while keeping its child dependencies linked:</p>
|
|
<p><pre class="listing"> atlas unlink --only other-project</pre></p>
|
|
|
|
<h3 id="use-slash-update-lturlgtslashltpackage-namegt">Use / Update <url>/<package name></h3><p><tt class="docutils literal"><span class="pre">atlas use <url|pkgname></span></tt> clones a package and its dependencies (recursively) into the project. It also creates or patches a <tt class="docutils literal"><span class="pre">nim.cfg</span></tt> file with the required <tt class="docutils literal"><span class="pre">--path</span></tt> entries.</p>
|
|
<p><tt class="docutils literal"><span class="pre">atlas update [filter]</span></tt> updates dependency remote refs in <tt class="docutils literal"><span class="pre">deps/</span></tt>, optionally filtered by package name or URL.</p>
|
|
<p>If a <tt class="docutils literal"><span class="pre"><package name></span></tt> is given instead the name is first translated into an URL via <tt class="docutils literal"><span class="pre">packages.json</span></tt> or via a github search.</p>
|
|
|
|
<h2 id="when-statements">When Statements</h2><p>When statements provide support for boolean expressions with a subset of compile time defines. The list of defines currently supported:</p>
|
|
<p>windows, posix, linux, macosx, freebsd, openbsd, netbsd, solaris; amd64, x86_64, i386, arm, arm64, mips, powerpc;</p>
|
|
<p>If a when statement isn't supported consider using <tt class="docutils literal"><span class="pre">feature</span></tt> statements instead.</p>
|
|
|
|
<h3 id="feature-statements">Feature Statements</h3><p>Features in Nimble files enable optional requirements for things different scenarios. This is useful when dealing with scenarios like testing only dependencies.</p>
|
|
<p><em>Note</em>: Features aren't saved to the Atlas config. Pass <tt class="docutils literal"><span class="pre">atlas --feature=foobar</span></tt> when doing commands that should enable a feature, or pass <tt class="docutils literal"><span class="pre">--keepFeatures</span></tt>/<tt class="docutils literal"><span class="pre">-k</span></tt> to reuse feature defines from the current <tt class="docutils literal"><span class="pre">nim.cfg</span></tt>.</p>
|
|
<p><pre class="listing"><span class="Identifier">require</span> <span class="StringLit">"normallib"</span>
|
|
|
|
<span class="Identifier">feature</span> <span class="StringLit">"testing"</span><span class="Punctuation">:</span>
|
|
<span class="Identifier">require</span> <span class="StringLit">"mytestlib"</span></pre></p>
|
|
<p>Features are lazily cloned by Atlas until they are specified by either a requires feature or passed from the command line.</p>
|
|
<p>In Nimble files you can enable features for a a given package like so:</p>
|
|
<p><pre class="listing"><span class="Identifier">require</span> <span class="StringLit">"somelib[testing]"</span>
|
|
<span class="Identifier">require</span> <span class="StringLit">"anotherlib[testing, async]"</span></pre></p>
|
|
|
|
<h3 id="search-ltterm-term2-term3-dotdotdotgt">Search <term term2 term3 ...></h3><p>Search the package index <tt class="docutils literal"><span class="pre">packages.json</span></tt> for a package that contains the given terms in its description (or name or list of tags).</p>
|
|
|
|
<h3 id="install">Install</h3><p>Use the project's <tt class="docutils literal"><span class="pre">.nimble</span></tt> file to set up dependencies.</p>
|
|
|
|
<h3 id="run-nimble-tasks">Run Nimble tasks</h3><p>Use <tt class="docutils literal"><span class="pre">atlas-run</span></tt> to list or run tasks from the current project's <tt class="docutils literal"><span class="pre">.nimble</span></tt> file:</p>
|
|
<p><pre class="listing">atlas-run task --list
|
|
atlas-run task docs
|
|
atlas-run --project path/to/project.nimble task test -- --flag</pre></p>
|
|
<p>Use <tt class="docutils literal"><span class="pre">atlas-run build</span></tt> to compile every binary declared by the project's <tt class="docutils literal"><span class="pre">.nimble</span></tt> file. Arguments after <tt class="docutils literal"><span class="pre">--</span></tt> are passed to the Nim compiler for each binary:</p>
|
|
<p><pre class="listing">atlas-run build
|
|
atlas-run build --list
|
|
atlas-run build -- -d:release --mm:orc</pre></p>
|
|
<p>Use <tt class="docutils literal"><span class="pre">atlas-run tests</span></tt> to run project tests matching <tt class="docutils literal"><span class="pre">tests/t*.nim</span></tt> in parallel. Successful compiler output is hidden by default; use <tt class="docutils literal"><span class="pre">--compiler-output</span></tt> to include it, and <tt class="docutils literal"><span class="pre">--only-errors</span></tt> to print only failed test chunks. Use <tt class="docutils literal"><span class="pre">--compile-only</span></tt> to compile matching tests without running them:</p>
|
|
<p>Selectors are positional arguments. A selector can be a test module name, filename, relative path, absolute path, or glob pattern; multiple selectors run each matched file once. Selectors without a path separator select discovered tests: <tt class="docutils literal"><span class="pre">foo</span></tt> matches <tt class="docutils literal"><span class="pre">tests/tfoo*.nim</span></tt>, and <tt class="docutils literal"><span class="pre">foo.nim</span></tt> matches <tt class="docutils literal"><span class="pre">tests/tfoo.nim</span></tt>. Selectors with a path separator are direct project-relative or absolute Nim files or glob patterns, so <tt class="docutils literal"><span class="pre">examples/*.nim</span></tt> selects those example files directly.</p>
|
|
<p>Compiler flags can be provided with <tt class="docutils literal"><span class="pre">NIMFLAGS</span></tt> or after <tt class="docutils literal"><span class="pre">--</span></tt>. When both are used, arguments after <tt class="docutils literal"><span class="pre">--</span></tt> are passed after <tt class="docutils literal"><span class="pre">NIMFLAGS</span></tt>, so they take precedence for repeated Nim compiler options. Use one or more <tt class="docutils literal"><span class="pre">--skip</span></tt> options after normal selectors to remove matching tests from the selected set.</p>
|
|
<p><pre class="listing">atlas-run tests
|
|
atlas-run tests --jobs:4
|
|
atlas-run tests --nimcache:.nimcache/atlas-run
|
|
atlas-run tests --no-shuffle
|
|
atlas-run tests --only-errors
|
|
atlas-run tests --compiler-output
|
|
atlas-run tests --compile-only
|
|
atlas-run tests --list
|
|
atlas-run tests tatlasrun
|
|
atlas-run tests --compile-only examples/*.nim
|
|
atlas-run tests t --skip integration --skip slow
|
|
NIMFLAGS="-d:release" atlas-run tests
|
|
atlas-run tests tatlasrun -- -d:release --mm:orc</pre></p>
|
|
|
|
<h3 id="update-filterfilter">Update <a class="reference internal" href="#filter">filter</a></h3><p>Update every dependency that matches <tt class="docutils literal"><span class="pre">filter</span></tt> by name or URL. If no filter is given, all dependencies are considered.</p>
|
|
|
|
<h3 id="others">Others</h3><p>Run <tt class="docutils literal"><span class="pre">atlas --help</span></tt> for more features.</p>
|
|
|
|
<h3 id="usage-with-ci">Usage With CI</h3><p>Atlas works well with CI since deps are installed in the cloned repo. Just cache the <tt class="docutils literal"><span class="pre">deps/</span></tt> dir.</p>
|
|
<p>Here's a snippet Github Actions YML:</p>
|
|
<p><pre class="listing"> ... Nim setup ...
|
|
|
|
- name: Install Latest Atlas (recommend until Nim's Atlas verision catches up in 2.2.8+)
|
|
run: |
|
|
nimble install 'https://github.com/nim-lang/atlas@#head'
|
|
|
|
- name: Cache packages
|
|
uses: actions/cache@v3
|
|
with:
|
|
path: deps/
|
|
key: ${{ runner.os }}-${{ hashFiles('foo.nimble') }}
|
|
|
|
- name: Install Deps
|
|
run: |
|
|
atlas install --feature=test --feature=other # etc</pre></p>
|
|
|
|
<h2 id="package-overrides">Package Overrides</h2><p>Sometimes two URLs can conflict for the same dependency shortname. For example, when a project uses a forked dependency with bug fixes. These conflicts need to be manually resolved using <tt class="docutils literal"><span class="pre">pkgOverrides</span></tt> in <tt class="docutils literal"><span class="pre">atlas.config</span></tt>. The format is package name and the selected URL:</p>
|
|
<p><pre class="listing"> "pkgOverrides": {
|
|
"asynctools": "https://github.com/timotheecour/asynctools"
|
|
},</pre></p>
|
|
<p>When a fork is involved, Atlas treats the URL in the dependency graph as canonical and ensures a corresponding git remote exists. It uses <tt class="docutils literal"><span class="pre">origin</span></tt> to store the canonical URL and also adds a named remote derived from the repo/author/host (e.g. <tt class="docutils literal"><span class="pre">repo.user.host</span></tt>) so it can resolve branch tips and special versions (like <tt class="docutils literal"><span class="pre">#branch</span></tt>) against the correct fork while still allowing an “official” remote to coexist for the upstream project.</p>
|
|
|
|
<h2 id="overrides">Overrides</h2><p>You can override how Atlas resolves a package name or a URL. The overrides use a simple pattern matching language and are flexible enough to integrate private gitlab repositories.</p>
|
|
<p><pre class="listing">{
|
|
"resolver": "SemVer",
|
|
"nameOverrides": {
|
|
"customProject": "https://gitlab.company.com/customProject"
|
|
},
|
|
"urlOverrides": {
|
|
"https://github.com/araq/ormin": "https://github.com/useMyForkInstead/ormin"
|
|
},
|
|
"plugins": "",
|
|
}
|
|
</pre></p>
|
|
<p>The <tt class="docutils literal"><span class="pre">$</span></tt> has a special meaning in a pattern:</p>
|
|
<table border="1" class="docutils"><tr><th>Syntax</th><th>Meaning</th></tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">$$</span></tt></td><td>Matches a single dollar sign.</td></tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">$*</span></tt></td><td>Matches until the token following the <tt class="docutils literal"><span class="pre">$*</span></tt> was found.</td></tr>
|
|
<tr><td></td><td>The match is allowed to be of 0 length.</td></tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">$+</span></tt></td><td>Matches until the token following the <tt class="docutils literal"><span class="pre">$+</span></tt> was found.</td></tr>
|
|
<tr><td></td><td>The match must consist of at least one char.</td></tr>
|
|
<tr><td><tt class="docutils literal"><span class="pre">$s</span></tt></td><td>Skips optional whitespace.</td></tr>
|
|
</table><p>For example, here is how to override any github link:</p>
|
|
<p><pre class="listing"> "urlOverrides": {
|
|
"https://github.com/$+": "https://utopia.forall/$#"
|
|
}</pre></p>
|
|
<p>You can use <tt class="docutils literal"><span class="pre">$1</span></tt> or <tt class="docutils literal"><span class="pre">$#</span></tt> to refer to captures.</p>
|
|
|
|
<h2 id="virtual-nim-environments">Virtual Nim environments</h2><p>Atlas supports setting up a virtual Nim environment via the <tt class="docutils literal"><span class="pre">env</span></tt> command. You can even install multiple different Nim versions into the same project.</p>
|
|
<p>For example:</p>
|
|
<p><pre class="listing">atlas env 1.6.12
|
|
atlas env devel</pre></p>
|
|
<p>For a tagged release, Atlas downloads the prebuilt binary for the current platform from the Nim release index. If that version or platform has no binary, Atlas builds Nim from source instead. Use <tt class="docutils literal"><span class="pre">--binary</span></tt> to require a binary or <tt class="docutils literal"><span class="pre">--source</span></tt> to always build from source:</p>
|
|
<p><pre class="listing">atlas env 2.2.10 --binary
|
|
atlas env 2.2.10 --source</pre></p>
|
|
<p>Binary downloads are verified when the release index provides a checksum. Download, checksum, and extraction failures are reported rather than falling back to a source build. The source path uses Nim's standard <tt class="docutils literal"><span class="pre">build_all.sh</span></tt> script on UNIX and <tt class="docutils literal"><span class="pre">build_all.bat</span></tt> on Windows. The <tt class="docutils literal"><span class="pre">devel</span></tt> version is always built from source, and <tt class="docutils literal"><span class="pre">atlas env devel --binary</span></tt> is an error.</p>
|
|
<p>In GitHub Actions, use <tt class="docutils literal"><span class="pre">--github-path</span></tt> to append the installed Nim <tt class="docutils literal"><span class="pre">bin</span></tt> directory to the runner's <tt class="docutils literal"><span class="pre">GITHUB_PATH</span></tt> environment file. Nim will then be available on <tt class="docutils literal"><span class="pre">PATH</span></tt> in subsequent steps of the current job:</p>
|
|
<p><pre class="listing">atlas env 2.2.10 --binary --github-path</pre></p>
|
|
<p>When completed, run <tt class="docutils literal"><span class="pre">source deps/nim-1.6.12/activate.sh</span></tt> on UNIX and <tt class="docutils literal"><span class="pre">deps\nim-1.6.12\activate.bat</span></tt> on Windows.</p>
|
|
|
|
<h2 id="dependency-resolution">Dependency resolution</h2><p>To change the used dependency resolution mechanism, edit the <tt class="docutils literal"><span class="pre">resolver</span></tt> value of your <tt class="docutils literal"><span class="pre">atlas.config</span></tt> file. The possible values are:</p>
|
|
|
|
<h3 id="maxver">MaxVer</h3><p>The default resolution mechanism is called "MaxVer" where the highest available version is selected that still fits the requirements.</p>
|
|
<p>Suppose you have a dependency called "mylibrary" with the following available versions: 1.0.0, 1.1.0, and 2.0.0. <tt class="docutils literal"><span class="pre">MaxVer</span></tt> selects the version 2.0.0.</p>
|
|
|
|
<h3 id="semver">SemVer</h3><p>Adhere to Semantic Versioning (SemVer) by selecting the highest version that satisfies the specified version range. SemVer follows the format of <tt class="docutils literal"><span class="pre">MAJOR.MINOR.PATCH</span></tt>, where:</p>
|
|
<p>MAJOR version indicates incompatible changes.</p>
|
|
<p>MINOR version indicates backward-compatible new features.</p>
|
|
<p>PATCH version indicates backward-compatible bug fixes.</p>
|
|
<p>Consider the same "mylibrary" dependency with versions 1.0.0, 1.1.0, and 2.0.0. If you set the resolver to <tt class="docutils literal"><span class="pre">SemVer</span></tt> and specify a version range requirement of <tt class="docutils literal"><span class="pre">>= 1.0.0</span></tt>, the highest version that satisfies the range that does not introduce incompatible changes will be selected. In this case, the selected version would be 1.1.0.</p>
|
|
|
|
<h3 id="minver">MinVer</h3><p>For the "mylibrary" dependency with versions 1.0.0, 1.1.0, and 2.0.0, if you set the resolver to <tt class="docutils literal"><span class="pre">MinVer</span></tt> and specify multiple minimum versions, the highest version among the minimum required versions will be selected. For example, if you specify a minimum requirement of both <tt class="docutils literal"><span class="pre">>=1.0.0</span></tt> and <tt class="docutils literal"><span class="pre">>=2.0.0</span></tt>, the selected version would be 2.0.0.</p>
|
|
|
|
<h2 id="reproducible-builds-slash-lockfiles">Reproducible builds / lockfiles</h2><p>Atlas supports lockfiles for reproducible builds via its <tt class="docutils literal"><span class="pre">pin</span></tt> and <tt class="docutils literal"><span class="pre">rep</span></tt> commands.</p>
|
|
<p><strong>Notice</strong>: Atlas helps with reproducible builds, but it is not a complete solution. For a truely reproducible build you also need to pin the used C++ compiler, any third party dependencies ("libc" etc.) and the version of your operating system.</p>
|
|
|
|
<h3 id="pin-atlasdotlockatlasdotlock">pin <a class="reference internal" href="#atlas.lock">atlas.lock</a></h3><p><tt class="docutils literal"><span class="pre">atlas pin</span></tt> can be run either in the project or in a specific project. It "pins" the used repositories to their current commit hashes. If run in the project the entire project is "pinned" in the <tt class="docutils literal"><span class="pre">atlas.lock</span></tt> file. If run in a project the project's dependencies but not the project itself is "pinned" in the lock file.</p>
|
|
|
|
<h3 id="rep-atlasdotlockatlasdotlock">rep <a class="reference internal" href="#atlas.lock">atlas.lock</a></h3><p>The <tt class="docutils literal"><span class="pre">rep</span></tt> command replays or repeats the projects to use the pinned commit hashes. If the projects have any "build" instructions these are performed too unless the <tt class="docutils literal"><span class="pre">--noexec</span></tt> switch is used.</p>
|
|
<p><tt class="docutils literal"><span class="pre">replay</span></tt> and <tt class="docutils literal"><span class="pre">reproduce</span></tt> are aliases for <tt class="docutils literal"><span class="pre">rep</span></tt>.</p>
|
|
|
|
<h2 id="plugins">Plugins</h2><p>Atlas operates on a graph of dependencies. A dependency is a git project of a specific commit. The graph and version selection algorithms are mostly programming language agnostic. Thus it is easy to integrate foreign projects as dependencies into your project.</p>
|
|
<p>This is accomplished by Atlas plugins. A plugin is a NimScript snippet that can call into external tools via <tt class="docutils literal"><span class="pre">exec</span></tt>.</p>
|
|
<p>To enable plugins, add the line <tt class="docutils literal"><span class="pre">plugins="_plugins"</span></tt> to your <tt class="docutils literal"><span class="pre">atlas.config</span></tt> file. Then create a directory <tt class="docutils literal"><span class="pre">_plugins</span></tt> in your project. Every <tt class="docutils literal"><span class="pre">*.nims</span></tt> file inside the plugins directory is integrated into Atlas.</p>
|
|
|
|
<h3 id="builders">Builders</h3><p>A builder is a build tool like <tt class="docutils literal"><span class="pre">make</span></tt> or <tt class="docutils literal"><span class="pre">cmake</span></tt>. What tool to use is determined by the existence of certain files in the project's top level directory. For example, a file <tt class="docutils literal"><span class="pre">CMakeLists.txt</span></tt> indicates a <tt class="docutils literal"><span class="pre">cmake</span></tt> based build:</p>
|
|
<p><pre class="listing">
|
|
<span class="Identifier">builder</span> <span class="StringLit">"CMakeLists.txt"</span><span class="Punctuation">:</span>
|
|
<span class="Identifier">mkDir</span> <span class="StringLit">"build"</span>
|
|
<span class="Identifier">withDir</span> <span class="StringLit">"build"</span><span class="Punctuation">:</span>
|
|
<span class="Identifier">exec</span> <span class="StringLit">"cmake .."</span>
|
|
<span class="Identifier">exec</span> <span class="StringLit">"cmake --build . --config Release"</span>
|
|
</pre></p>
|
|
<p>Save this as <tt class="docutils literal"><span class="pre">_plugins/cmake.nims</span></tt>. Then every dependency that contains a <tt class="docutils literal"><span class="pre">CMakeLists.txt</span></tt> file will be build with <tt class="docutils literal"><span class="pre">cmake</span></tt>.</p>
|
|
<p><strong>Note</strong>: To disable any kind of action that might run arbitrary code, use the <tt class="docutils literal"><span class="pre">--noexec</span></tt> switch. </p>
|
|
|
|
|
|
|
|
<div class="twelve-columns footer">
|
|
<span class="nim-sprite"></span>
|
|
<br>
|
|
<small style="color: var(--hint);">Made with Nim. Generated: 2026-08-29 12:49:44 UTC</small>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<script defer data-domain="nim-lang.org" src="https://plausible.io/js/plausible.js"></script>
|
|
|
|
</body>
|
|
</html>
|