### Initialize and use dependencies

Source: https://github.com/nim-lang/atlas/blob/master/readme.md

Clone a project, install dependencies, and add specific libraries.

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

```sh
atlas use malebolgia
```

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

--------------------------------

### Setup workspace-style configuration

Source: https://github.com/nim-lang/atlas/blob/master/readme.md

Configure a shared dependencies folder for multiple projects.

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

--------------------------------

### Setup Test Repositories

Source: https://github.com/nim-lang/atlas/blob/master/AGENTS.md

Initializes the test cache by downloading necessary repositories for testing purposes.

```nim
nim testReposSetup
```

--------------------------------

### Atlas Nim Configuration Example

Source: https://github.com/nim-lang/atlas/blob/master/doc/atlas.md

Shows an example of the 'nim.cfg' file generated or patched by Atlas, including paths to dependencies and linked projects.

```nim
############# 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   ##########
```

--------------------------------

### Project structure example

Source: https://github.com/nim-lang/atlas/blob/master/readme.md

The default directory layout created by Atlas.

```text
  $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)
```

--------------------------------

### Setup Workspace Style Dependencies

Source: https://context7.com/nim-lang/atlas/llms.txt

Configures a shared directory for dependencies across multiple projects.

```bash
# Create a workspace directory
mkdir workspace && cd workspace

# Clone and set up the first project
git clone https://github.com/nim-lang/choosenim
cd choosenim
atlas --deps=../ --confdir=. init
atlas install

# Now all deps are in workspace/ and can be shared with other projects
cd ..
git clone https://github.com/another/project
cd project
atlas --deps=../ --confdir=. init
atlas install
```

--------------------------------

### Install Atlas via Nimble

Source: https://github.com/nim-lang/atlas/blob/master/readme.md

Use the Nimble package manager to install the latest version of Atlas.

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

--------------------------------

### Install Atlas and Dependencies in GitHub Actions

Source: https://github.com/nim-lang/atlas/blob/master/doc/atlas.md

Example of installing the latest Atlas version and dependencies, including features, within a GitHub Actions workflow. Caching the 'deps/' directory is recommended for performance.

```yaml
    ... 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
```

--------------------------------

### Integrate with GitHub Actions

Source: https://context7.com/nim-lang/atlas/llms.txt

Automates dependency installation and caching in CI/CD pipelines.

```yaml
# GitHub Actions example
name: CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - uses: jiro4989/setup-nim-action@v1
        with:
          nim-version: '2.0.0'

      - name: Install Atlas
        run: nimble install 'https://github.com/nim-lang/atlas@#head'

      - name: Cache dependencies
        uses: actions/cache@v3
        with:
          path: deps/
          key: ${{ runner.os }}-${{ hashFiles('project.nimble') }}

      - name: Install dependencies
        run: atlas install --feature=test

      - name: Build
        run: nim c -r src/main.nim
```

--------------------------------

### Install Project Dependencies

Source: https://context7.com/nim-lang/atlas/llms.txt

Clones dependencies defined in the .nimble file into the local workspace. Use feature flags for conditional dependencies or skip build hooks with --noexec.

```bash
# Install dependencies from the project's nimble file
atlas install

# Install with feature flags for conditional dependencies
atlas --feature=testing --feature=async install

# Install without executing any build hooks
atlas --noexec install
```

--------------------------------

### Add Packages with Use

Source: https://context7.com/nim-lang/atlas/llms.txt

Adds dependencies by name or URL to the project. Includes options to force HTTPS for git URLs and a workflow example for new projects.

```bash
# Add a package by name
atlas use malebolgia

# Add a package by URL
atlas use https://github.com/zedeus/nitter

# Add a package and force git:// URLs to https://
atlas --forceGitToHttps use somepackage

# Example workflow for a new project
mkdir newproject && cd newproject
git init
atlas use lexim
echo 'import lexim' > example.nim
nim c example.nim
```

--------------------------------

### Manage Virtual Nim Environments

Source: https://context7.com/nim-lang/atlas/llms.txt

Installs specific Nim compiler versions and provides activation scripts for isolated environments. Deactivate the environment when finished.

```bash
# Install a specific Nim version
atlas env 2.0.0

# Install the development version
atlas env devel

# Activate the environment (Unix)
source deps/nim-2.0.0/activate.sh

# Activate the environment (Windows cmd)
.\deps\nim-2.0.0\activate.bat

# Activate the environment (PowerShell)
. .\deps\nim-2.0.0\activate.ps1

# Deactivate when done
deactivate
```

--------------------------------

### Set Up Virtual Nim Environment

Source: https://github.com/nim-lang/atlas/blob/master/doc/atlas.md

Use the 'atlas env' command to set up a virtual Nim environment within a project. This allows installing multiple Nim versions in the same project.

```shell
atlas env 1.6.12
atlas env devel
```

--------------------------------

### Define Feature-Based Dependencies

Source: https://context7.com/nim-lang/atlas/llms.txt

Declares optional dependencies in Nimble files and installs them using feature flags.

```nim
# In project.nimble
requires "normallib"

feature "testing":
  requires "unittest2"
  requires "mockable"

feature "async":
  requires "chronos"
```

```bash
# Install with testing dependencies
atlas --feature=testing install

# Install with multiple features
atlas --feature=testing --feature=async install

# Package-scoped features
atlas --feature=mypackage.testing install
```

--------------------------------

### URL Override Pattern Matching

Source: https://github.com/nim-lang/atlas/blob/master/doc/atlas.md

Example of overriding any GitHub link using pattern matching in 'atlas.config'. The '$+' matches one or more characters, and '$#' refers to captures.

```json
  "urlOverrides": {
    "https://github.com/$+": "https://utopia.forall/$#"
  }
```

--------------------------------

### Package Overrides Configuration

Source: https://github.com/nim-lang/atlas/blob/master/doc/atlas.md

Configure package overrides in 'atlas.config' to manually resolve conflicts between different URLs for the same dependency shortname. This example shows overriding 'asynctools'.

```json
  "pkgOverrides": {
    "asynctools": "https://github.com/timotheecour/asynctools"
  },
```

--------------------------------

### Initialize and Use a Package with Atlas

Source: https://github.com/nim-lang/atlas/blob/master/doc/atlas.md

Demonstrates the basic workflow of creating a new project, initializing it, and using a package like 'lexim' with Atlas.

```bash
  mkdir newproject
  cd newproject
  git init
  atlas use lexim
  # add `import lexim` to your example.nim file
  nim c example.nim
```

--------------------------------

### Try the CLI

Source: https://github.com/nim-lang/atlas/blob/master/AGENTS.md

Launches the Atlas command-line interface with the help flag to display available commands and options.

```bash
bin/atlas --help
```

--------------------------------

### Manage dependencies via URLs and links

Source: https://github.com/nim-lang/atlas/blob/master/readme.md

Add dependencies using direct URLs or link to existing local folders.

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

```sh
atlas link ../../existingDependency/
```

--------------------------------

### Initialize Atlas Project

Source: https://context7.com/nim-lang/atlas/llms.txt

Sets up a new project with a deps/ directory and configuration file. Supports custom directory paths and global workspace initialization.

```bash
# Initialize a new project
atlas init

# Initialize with a custom deps directory (workspace style)
atlas --deps=../ --confdir=. init

# Initialize a global workspace in ~/.atlas
atlas --global init
```

--------------------------------

### Create Build System Plugins

Source: https://context7.com/nim-lang/atlas/llms.txt

Integrates non-Nim build systems using NimScript files in the plugins directory.

```nim
# _plugins/cmake.nims - CMake integration
builder "CMakeLists.txt":
  mkDir "build"
  withDir "build":
    exec "cmake .."
    exec "cmake --build . --config Release"
```

```nim
# _plugins/scons.nims - SCons integration
builder "SConstruct":
  exec "scons"
```

```nim
# _plugins/make.nims - Make integration
builder "Makefile":
  exec "make"
```

--------------------------------

### Manage Version Tags

Source: https://context7.com/nim-lang/atlas/llms.txt

Automates semantic versioning for projects by managing git tags.

```bash
# Increment patch version (0.1.0 -> 0.1.1)
atlas tag patch

# Increment minor version (0.1.1 -> 0.2.0)
atlas tag minor

# Increment major version (0.2.0 -> 1.0.0)
atlas tag major

# Set a specific version tag
atlas tag 1.0.3

# Set a letter tag
atlas tag a
```

--------------------------------

### Run All Tests

Source: https://github.com/nim-lang/atlas/blob/master/AGENTS.md

Executes all unit and integration tests. This command will also download necessary test repositories if they are missing.

```nim
nim test
```

--------------------------------

### Atlas CLI Options Reference

Source: https://context7.com/nim-lang/atlas/llms.txt

List of available options for configuring Atlas behavior.

```bash
atlas --help, -h              Show help
```

```bash
atlas --version, -v           Show version
```

```bash
atlas --project=path, -p      Use project at given path
```

```bash
atlas --deps=path             Override deps directory
```

```bash
atlas --confdir=path          Use atlas.config at given path
```

```bash
atlas --feature=<feature>     Enable feature flag
```

```bash
atlas --resolver=<algo>       Resolution algorithm (minver|semver|maxver)
```

```bash
atlas --keepCommits           Don't perform git checkouts
```

```bash
atlas --noexec                Don't run arbitrary code
```

```bash
atlas --autoenv               Auto-setup Nim virtual environment
```

```bash
atlas --proxy=url             Proxy URL for git operations
```

```bash
atlas --forceGitToHttps       Force git:// to https://
```

```bash
atlas --colors=on|off         Toggle colored output
```

```bash
atlas --verbosity=<level>     Set verbosity (normal|info|warn|error|trace|debug)
```

--------------------------------

### Build Atlas from source

Source: https://github.com/nim-lang/atlas/blob/master/readme.md

Compile the Atlas tool from its GitHub repository.

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

--------------------------------

### Manage Reproducible Builds

Source: https://context7.com/nim-lang/atlas/llms.txt

Pins current dependency states to lockfiles for reproducibility and replays them later. Supports checking for drift between current state and lockfile.

```bash
# Pin current dependency state to atlas.lock
atlas pin

# Pin to a custom lockfile
atlas pin custom.lock

# Export to Nimble lockfile format
atlas pin nimble.lock

# Replay/reproduce from a lockfile
atlas rep atlas.lock

# Replay without executing build hooks
atlas --noexec rep atlas.lock

# Check for differences from lockfile
atlas changed atlas.lock
```

--------------------------------

### Search Package Index

Source: https://context7.com/nim-lang/atlas/llms.txt

Queries the package index for matches based on name, description, or tags.

```bash
# Search for packages
atlas search http json parser

# Search for specific functionality
atlas search async websocket
```

--------------------------------

### Generate Documentation

Source: https://github.com/nim-lang/atlas/blob/master/AGENTS.md

Generates the project's documentation. This can be done using either the `nim docs` or `nimble docs` command.

```nim
nim docs
```

```nim
nimble docs
```

--------------------------------

### Build Release Binary

Source: https://github.com/nim-lang/atlas/blob/master/AGENTS.md

Creates an optimized release binary for the project. Cross-architecture rules are defined within `config.nims`.

```nim
nim buildRelease
```

--------------------------------

### Atlas Commands Reference

Source: https://context7.com/nim-lang/atlas/llms.txt

List of available commands for managing Nim projects and dependencies with Atlas.

```bash
atlas init                    Initialize current directory as Atlas project
```

```bash
atlas use <url|pkgname>       Add package and dependencies to project
```

```bash
atlas install                 Install dependencies from nimble file
```

```bash
atlas update [filter]         Update dependencies matching filter
```

```bash
atlas search <terms...>       Search package index
```

```bash
atlas link <path>             Link another project's dependencies
```

```bash
atlas tag <version>           Create and push git tag
```

```bash
atlas pin [lockfile]          Pin dependencies to lockfile
```

```bash
atlas rep [lockfile]          Replay dependencies from lockfile
```

```bash
atlas changed [lockfile]      List packages differing from lockfile
```

```bash
atlas outdated                List packages with newer versions
```

```bash
atlas env <nimversion>        Setup Nim virtual environment
```

--------------------------------

### Debug and Verbose Output

Source: https://context7.com/nim-lang/atlas/llms.txt

Provides commands for inspecting dependency resolution, graphs, and workspace artifacts.

```bash
# Verbose output levels
atlas --verbosity=info install
atlas --verbosity=debug install
atlas --verbosity=trace install

# Show dependency graph (requires Graphviz)
atlas --showGraph install

# Dump SAT formula for debugging version conflicts
atlas --dumpformular install

# Dump dependency graphs to JSON files
atlas --dumpgraphs install

# Keep workspace artifacts for inspection
atlas --keepworkspace install
```

--------------------------------

### Use a Package with Atlas

Source: https://github.com/nim-lang/atlas/blob/master/doc/atlas.md

Clones a package and its dependencies into the 'deps' directory, patching 'nim.cfg' for module availability. Can use URL or package name.

```bash
atlas use <url|pkgname>
```

--------------------------------

### Run Integration Tests

Source: https://github.com/nim-lang/atlas/blob/master/AGENTS.md

Executes the integration tests for the project.

```nim
nim tester
```

--------------------------------

### Define a CMake builder plugin

Source: https://github.com/nim-lang/atlas/blob/master/doc/atlas.md

Create a NimScript file in the _plugins directory to define custom build steps for projects containing a CMakeLists.txt file.

```nim
builder "CMakeLists.txt":
  mkDir "build"
  withDir "build":
    exec "cmake .."
    exec "cmake --build . --config Release"
```

--------------------------------

### Link Another Project with Atlas

Source: https://github.com/nim-lang/atlas/blob/master/doc/atlas.md

Shows how to link another Atlas project into the current project to share dependencies. The linked project must have an Atlas file.

```bash
  atlas link ../other-project
```

--------------------------------

### Configure atlas.config

Source: https://context7.com/nim-lang/atlas/llms.txt

Defines dependency paths, URL overrides, package overrides, and resolution settings in JSON format.

```json
{
  "deps": "deps/",
  "nameOverrides": {
    "customProject": "https://gitlab.company.com/customProject"
  },
  "urlOverrides": {
    "https://github.com/araq/ormin": "https://github.com/useMyForkInstead/ormin",
    "https://github.com/$+": "https://utopia.forall/$#"
  },
  "pkgOverrides": {
    "asynctools": "https://github.com/timotheecour/asynctools"
  },
  "plugins": "_plugins",
  "resolver": "SemVer"
}
```

--------------------------------

### Link Atlas Projects

Source: https://context7.com/nim-lang/atlas/llms.txt

Shares dependencies between projects by creating nimble-link files, avoiding redundant clones.

```bash
# Link an existing project
atlas link ../other-project

# Link using the nimble file path directly
atlas link ../other-project/other.nimble
```

--------------------------------

### Check Outdated Packages

Source: https://context7.com/nim-lang/atlas/llms.txt

Lists dependencies that have newer versions available in their remote repositories.

```bash
# List outdated packages
atlas outdated
```

--------------------------------

### Atlas CLI Usage

Source: https://context7.com/nim-lang/atlas/llms.txt

Basic structure for using the Atlas command line tool. Specify options and commands with their arguments.

```bash
atlas [options] [command] [arguments]
```

--------------------------------

### Manage Nim environments

Source: https://github.com/nim-lang/atlas/blob/master/readme.md

Activate specific Nim versions using Atlas across different shells.

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

```cmd
.\deps\nim-2.0.0\activate.bat
```

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

```sh
deactivate
```

--------------------------------

### Enable Features for a Package

Source: https://github.com/nim-lang/atlas/blob/master/doc/atlas.md

Enable specific features for a package within Nimble files by including the feature name in square brackets after the package name.

```nim
require "somelib[testing]"
require "anotherlib[testing, async]"
```

--------------------------------

### Set Resolution Algorithms

Source: https://context7.com/nim-lang/atlas/llms.txt

Controls how Atlas selects dependency versions via command line flags.

```bash
# Use semantic versioning (default) - highest compatible version
atlas --resolver=semver install

# Use minimum version - lowest satisfying version
atlas --resolver=minver install

# Use maximum version - highest available version regardless of compatibility
atlas --resolver=maxver install
```

--------------------------------

### Build Debug Binary

Source: https://github.com/nim-lang/atlas/blob/master/AGENTS.md

Compiles the project to produce a debug binary located at `bin/atlas`. This command uses the configuration specified in `config.nims`.

```nim
nim build
```

--------------------------------

### Atlas configuration file

Source: https://github.com/nim-lang/atlas/blob/master/readme.md

The JSON structure for the atlas.config file.

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

--------------------------------

### Atlas Project Structure

Source: https://github.com/nim-lang/atlas/blob/master/doc/atlas.md

Illustrates the typical directory structure of an Atlas project, including the main project files, the 'deps/' directory, and linked project files.

```text
  $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)
```

--------------------------------

### Run Unit Tests Only

Source: https://github.com/nim-lang/atlas/blob/master/AGENTS.md

Executes only the unit tests for the project.

```nim
nim unitTests
```

--------------------------------

### Placeholder Version Entry in Atlas Graph

Source: https://github.com/nim-lang/atlas/blob/master/doc/solver.md

In lazy mode, a placeholder version entry (`*@-` with a `#head` release payload) is used for lazy packages to maintain graph connectivity.

```nim
"*@-" & "#head"
```

--------------------------------

### Update Dependencies

Source: https://context7.com/nim-lang/atlas/llms.txt

Refreshes remote references for dependencies. Can be scoped to specific packages or run with verbose output.

```bash
# Update all dependencies
atlas update

# Update only dependencies matching a filter
atlas update malebolgia

# Update with verbose output
atlas --verbosity=info update
```

--------------------------------

### General Overrides Configuration

Source: https://github.com/nim-lang/atlas/blob/master/doc/atlas.md

Configure general overrides in 'atlas.config' for name and URL matching, including custom project names and Gitlab repositories. Supports pattern matching with special characters like '$*'.

```json
{
  "resolver": "SemVer",
  "nameOverrides": {
    "customProject": "https://gitlab.company.com/customProject"
  },
  "urlOverrides": {
    "https://github.com/araq/ormin": "https://github.com/useMyForkInstead/ormin"
  },
  "plugins": "",
}
```

--------------------------------

### Force Eager Dependency Loading in Atlas

Source: https://github.com/nim-lang/atlas/blob/master/doc/solver.md

Users can force the previous eager dependency loading behavior by using the `--no-lazy-deps` command-line flag. This bypasses the lazy rerun loop.

```bash
--no-lazy-deps
```

--------------------------------

### Enable Lazy Dependencies in Atlas

Source: https://github.com/nim-lang/atlas/blob/master/doc/solver.md

Lazy dependency loading is enabled when both `doSolve` is true and the traversal mode is `AllReleases`. This behavior can be overridden.

```nim
deferChildDeps = doSolve and mode == AllReleases
```

--------------------------------

### Define Feature in Nimble File

Source: https://github.com/nim-lang/atlas/blob/master/doc/atlas.md

Use feature statements in Nimble files to define optional requirements for different scenarios, such as testing dependencies. Features are lazily cloned by Atlas until specified.

```nim
require "normallib"

feature "testing":
  require "mytestlib"
```

--------------------------------

### Update Dependencies with Atlas

Source: https://github.com/nim-lang/atlas/blob/master/doc/atlas.md

Updates remote references for dependencies in the 'deps/' directory. Can optionally filter by package name or URL.

```bash
atlas update [filter]
```

--------------------------------

### Atlas Rerun Mechanics

Source: https://github.com/nim-lang/atlas/blob/master/doc/solver.md

When a rerun is necessary due to newly promoted `DoLoad` packages, Atlas resets version IDs, clears feature mappings, expands the graph again, and re-solves the SAT problem.

```nim
version var IDs are reset,
feature var mappings are cleared,
graph is expanded again with newly promoted `DoLoad` packages,
SAT is rebuilt and solved again.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.