The Atlas Package cloner. It manages project dependencies in an isolated deps/ directory.

Installation

Nim version 2.0 ships with atlas. Note that this version may be slightly outdated.

Building from source:

git clone https://github.com/nim-lang/atlas.git
cd atlas/
nim build
# copy bin/atlas[.exe] and bin/atlas-run[.exe] somewhere in your PATH

Install with the bootstrap script:

curl -fsSL https://raw.githubusercontent.com/nim-lang/atlas/HEAD/install.sh | bash -

This clones and builds Atlas in /tmp and installs atlas and atlas-run into ~/.nimble/bin by default. To install somewhere else:

curl -fsSL https://raw.githubusercontent.com/nim-lang/atlas/HEAD/install.sh | \
  ATLAS_INSTALL_DIR="$HOME/.local/bin" bash -

Supported installer environment variables: ATLAS_INSTALL_DIR, ATLAS_REF, ATLAS_REPO_URL, ATLAS_TMP_ROOT.

If you're using Nimble you can install the latest Atlas with:

nimble install "https://github.com/nim-lang/atlas@#head"

Documentation

Read the full documentation or go through the following tutorial.

Tutorial

Clone or create a Nim project. For example:

git clone https://github.com/nim-lang/sat
cd sat/
atlas install

Tell Atlas we want to use the "malebolgia" library:

atlas use malebolgia

Now import malebolgia in your Nim code and run the compiler as usual:

echo "import malebolgia" >myproject.nim
nim c myproject.nim

How it Works

Atlas works by creating a nim.cfg file with the proper compiler configs. No magic! Just delete nim.cfg to clear the configs.

The project structure will default to something similar to this:

  $project / project.nimble
  $project / nim.cfg
  $project / other main project files...
  $project / deps / atlas.config
  $project / deps / malebolgia
  $project / deps / dependency-A
  $project / deps / dependency-B
  $project / deps / dependency-C.nimble-link (for linked projects)

Atlas Config

The atlas.config file is where Atlas project settings can be changed. Atlas defaults to finding it at ./deps/atlas.config and is a simple JSON file. A default config is automatically created there if one is not found.

Additionally Atlas checks the current project folder for an ./atlas.config file. This setup lets you override the deps folder location where dependencies are stored. See Workspace Style Setup below.

You can also add or override URLs, package names, etc there as well. The current supported options are:

{
  "deps": "../",
  "nameOverrides": {},
  "urlOverrides": {},
  "pkgOverrides": {},
  "plugins": "",
  "resolver": "SemVer"
}

See the full documentation for more details on nameOverrides and others.

Using URLs and local folders

Use URLs:

atlas use https://github.com/zedeus/nitter

If your dependency metadata uses git:// remotes, pass --forceGitToHttps to rewrite them to https:// before cloning.

Link to another project and its deps:

atlas link ../../existingDependency/

Manually Changing Deps

All dependencies are full git repos. You can manually go into deps/ and change the branch, add new origins, make experimental changes, etc.

Workspace Style Setup

Multiple projects can share a single deps folder.

In this configuration Atlas works in a workspace style. All you need to do is setup an atlas.config in each project.

To setup a folder ws/ as a workspace simply clone a project into the ws/ folder like:

mkdir ws/ && cd ws/
git clone https://github.com/nim-lang/choosenim
cd choosenim/
atlas --deps=../ --confdir=. init
atlas install

Now ws/ contains all the dependencies for choosenim such as zippy, checksums, etc.

Note: The deps config setting can be relative or absolute. So you could do a global workspace like atlas --deps=~/ws/ --confdir=. init.

Debugging

Sometimes it's helpful to understand what Atlas is doing. You can run commands with atlas --verbosity=info (or --verbosity=debug) to get more information.

Running Nimble Tasks

atlas-run runs tasks from the current project's .nimble file without using Nimble:

atlas-run task --list
atlas-run task docs
atlas-run --project path/to/project.nimble task test -- --flag

atlas-run build builds every binary declared by the project's .nimble file:

atlas-run build
atlas-run build --list

atlas-run tests is a built-in test runner. It runs project tests matching tests/t*.nim in parallel and prints each test's captured output as a complete chunk when that test finishes. Successful compiler output is hidden by default; use --compiler-output to include it, and --only-errors to print only failed test chunks. Use --compile-only to compile matching tests without running them.

Selectors without a path separator select discovered tests: foo matches tests/tfoo*.nim, and foo.nim matches tests/tfoo.nim. Selectors with a path separator are direct project-relative or absolute Nim files or glob patterns, so examples/*.nim selects those example files directly:

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

Installing Nim with Atlas

You can use atlas to set up a nim virtual environment:

atlas env 2.0.0
source deps/nim-2.0.0/activate.sh

You can do the same on a windows cmd shell:

.\deps\nim-2.0.0\activate.bat

And in powershell:

. .\deps\nim-2.0.0\activate.ps1

After executing these commands, the specific nim version you chose will be available in your current shell.

To get back to the original setup you can run:

deactivate

Dependencies

Atlas places dependencies in a deps/ directory. This is especially helpful for working with projects that have dependencies pinned as git submodules, which was common in the pre-Atlas era.

The deps/ directory contains:

• atlas.config: Configuration file for dependency management
• Individual dependency directories
• nimble-link files for linked projects

Note that atlas.config file can be placed in the main project directory as well. In this case, the dependencies directory can modified by setting the deps field.