levovix
/
Nim
kopia lustrzana https://github.com/nim-lang/Nim


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158
							<?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">
    <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 an isolated workspace that contains projects and dependencies.</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 three concepts:</p>
<ol class="simple"><li>Workspaces</li>
<li>Projects</li>
<li>Dependencies</li>
</ol>

<h3 id="workspaces">Workspaces</h3><p>Every workspace is isolated, nothing is shared between workspaces. A workspace is a directory that has a file <tt class="docutils literal"><span class="pre">atlas.workspace</span></tt> inside it. Use <tt class="docutils literal"><span class="pre">atlas init</span></tt> to create a workspace out of the current working directory.</p>
<p>Projects plus their dependencies are stored in a workspace:</p>
<p><pre class="listing">  $workspace / main project
  $workspace / other project
  $workspace / _deps / dependency A
  $workspace / _deps / dependency B</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="projects">Projects</h3><p>A workspace contains one or multiple &quot;projects&quot;. These projects can use each other and it is easy to develop multiple projects at the same time.</p>

<h3 id="dependencies">Dependencies</h3><p>Inside a workspace there can be 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 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 <tt class="docutils literal"><span class="pre">git show-ref --tags</span></tt>.</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.</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:&quot;../nimx&quot;
--path:&quot;../sdl2/src&quot;
--path:&quot;../opengl/src&quot;
############# 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>Atlas supports the following commands:</p>

<h3 id="use-lturlgt-slash-ltpackage-namegt">Use &lt;url&gt; / &lt;package name&gt;</h3><p>Clone the package behind <tt class="docutils literal"><span class="pre">url</span></tt> or <tt class="docutils literal"><span class="pre">package name</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 which should be in the current working directory. 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
  # add `import lexim` to your example.nim file
  nim c example.nim
</pre></p>

<h3 id="cloneslashupdate-lturlgtslashltpackage-namegt">Clone/Update &lt;url&gt;/&lt;package name&gt;</h3><p>Clones a URL and all of its dependencies (recursively) into the workspace. 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><strong>Note</strong>: Due to the used algorithms an <tt class="docutils literal"><span class="pre">update</span></tt> is the same as a <tt class="docutils literal"><span class="pre">clone</span></tt>.</p>
<p>If a <tt class="docutils literal"><span class="pre">&lt;package name&gt;</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>

<h3 id="search-ltterm-term2-term3-dotdotdotgt">Search &lt;term term2 term3 ...&gt;</h3><p>Search the package index <tt class="docutils literal"><span class="pre">packages.json</span></tt> for a package that the given terms in its description (or name or list of tags).</p>

<h3 id="install-ltprojdotnimblegt">Install &lt;proj.nimble&gt;</h3><p>Use the .nimble file to setup the project's dependencies.</p>

<h3 id="updateprojects-slash-updatedeps-filterfilter">UpdateProjects / updateDeps <a class="reference internal" href="#filter">filter</a></h3><p>Update every project / dependency in the workspace that has a remote URL that matches <tt class="docutils literal"><span class="pre">filter</span></tt> if a filter is given. The project / dependency is only updated if there are no uncommitted changes.</p>

<h3 id="others">Others</h3><p>Run <tt class="docutils literal"><span class="pre">atlas --help</span></tt> for more features.</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>To setup an override file, edit the <tt class="docutils literal"><span class="pre">$workspace/atlas.workspace</span></tt> file to contain a line like <tt class="docutils literal"><span class="pre">overrides=&quot;urls.rules&quot;</span></tt>. Then create a file <tt class="docutils literal"><span class="pre">urls.rules</span></tt> that can contain lines like:</p>
<p><pre class="listing">customProject -&gt; https://gitlab.company.com/customProject
https://github.com/araq/ormin -&gt; https://github.com/useMyForkInstead/ormin</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">https://github.com/$+ -&gt; 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 workspace.</p>
<p>For example:</p>
<p><pre class="listing">atlas env 1.6.12
atlas env devel</pre></p>
<p>When completed, run <tt class="docutils literal"><span class="pre">source nim-1.6.12/activate.sh</span></tt> on UNIX and <tt class="docutils literal"><span class="pre">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.workspace</span></tt> file. The possible values are:</p>

<h3 id="maxver">MaxVer</h3><p>The default resolution mechanism is called &quot;MaxVer&quot; where the highest available version is selected that still fits the requirements.</p>
<p>Suppose you have a dependency called &quot;mylibrary&quot; 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 &quot;mylibrary&quot; 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">&gt;= 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 &quot;mylibrary&quot; 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">&gt;=1.0.0</span></tt> and <tt class="docutils literal"><span class="pre">&gt;=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 (&quot;libc&quot; 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 workspace or in a specific project. It &quot;pins&quot; the used repositories to their current commit hashes. If run in the workspace the entire workspace is &quot;pinned&quot; 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 &quot;pinned&quot; 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 &quot;build&quot; instructions these are performed too unless the <tt class="docutils literal"><span class="pre">--noexec</span></tt> switch is used.</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=&quot;_plugins&quot;</span></tt> to your <tt class="docutils literal"><span class="pre">atlas.workspace</span></tt> file. Then create a directory <tt class="docutils literal"><span class="pre">_plugins</span></tt> in your workspace. 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">&quot;CMakeLists.txt&quot;</span><span class="Punctuation">:</span>
  <span class="Identifier">mkDir</span> <span class="StringLit">&quot;build&quot;</span>
  <span class="Identifier">withDir</span> <span class="StringLit">&quot;build&quot;</span><span class="Punctuation">:</span>
    <span class="Identifier">exec</span> <span class="StringLit">&quot;cmake ..&quot;</span>
    <span class="Identifier">exec</span> <span class="StringLit">&quot;cmake --build . --config Release&quot;</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: 2025-02-03 14:56:38 UTC</small>
      </div>
    </div>
  </div>
      <script defer data-domain="nim-lang.org" src="https://plausible.io/js/plausible.js"></script>
    
</body>
</html>