https://github.com/asdf-community/asdf-nim
Nim plugin for the asdf version manager [maintainer=@elijahr]
https://github.com/asdf-community/asdf-nim
asdf asdf-plugin
Last synced: 3 months ago
JSON representation
Nim plugin for the asdf version manager [maintainer=@elijahr]
- Host: GitHub
- URL: https://github.com/asdf-community/asdf-nim
- Owner: asdf-community
- License: apache-2.0
- Created: 2021-01-01T00:26:19.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2026-03-04T04:20:14.000Z (3 months ago)
- Last Synced: 2026-03-04T09:41:31.910Z (3 months ago)
- Topics: asdf, asdf-plugin
- Language: Shell
- Homepage: https://github.com/asdf-vm/asdf
- Size: 497 KB
- Stars: 27
- Watchers: 1
- Forks: 11
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: contributing.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
[](https://github.com/asdf-community/asdf-nim/actions/workflows/build.yml) [](https://github.com/asdf-community/asdf-nim/actions/workflows/lint.yml)
# asdf-nim
asdf-nim allows you to quickly install any version of [Nim](https://nim-lang.org).
asdf-nim works for both personal development and continuous integration. It runs on macOS and Linux, supporting x86, ARM, and other architectures.
## Installation
[Install asdf](https://asdf-vm.com/guide/getting-started.html), then:
```sh
asdf plugin add nim # install the asdf-nim plugin
asdf nim install-deps # install system-specific dependencies for downloading & building Nim
```
### To install Nim:
When available for the version and platform, the plugin will install pre-compiled binaries of Nim. If no binaries are available the plugin will build Nim from source.
```sh
# latest stable version of Nim
asdf install nim latest
# or latest stable minor/patch release of Nim 2.x.x
asdf install nim latest:2
# or latest stable patch release of Nim 2.2.x
asdf install nim latest:2.2
# or specific patch release
asdf install nim 2.2.0
```
### To install a nightly build of Nim:
Pre-built nightly binaries are available for some platforms and branches:
```sh
# nightly unstable build of devel branch (pre-built binaries available for most platforms)
asdf install nim ref:devel
# or nightly unstable build of version-2-2 branch (pre-built binaries available for most platforms)
asdf install nim ref:version-2-2
# or nightly unstable build of version-2-0 branch (pre-built binaries available for most platforms)
asdf install nim ref:version-2-0
```
For older versions, the plugin will build from source (no pre-built nightly binaries):
```sh
# build from version-1-6 branch source (no pre-built nightlies available)
asdf install nim ref:version-1-6
```
### To build a specific git commit or branch of Nim:
```sh
# build using latest commit from the devel branch
asdf install nim ref:HEAD
# build using the specific commit 7d15fdd
asdf install nim ref:7d15fdd
# build using the tagged release v2.2.0
asdf install nim ref:v2.2.0
```
### To set the default version of Nim for your user:
```sh
asdf set --home nim latest:2.2
```
This creates a `.tool-versions` file in your home directory specifying the Nim version.
### To set the version of Nim for a project directory:
```sh
cd my-project
asdf set nim latest:2.2
```
This creates a `.tool-versions` file in the current directory specifying the Nim version. For additional plugin usage see the [asdf documentation](https://asdf-vm.com/#/core-manage-asdf).
## Nimble packages
In addition to global nimble package installation, asdf-nim works as expected with a[`nimbledeps`](https://github.com/nim-lang/nimble/issues/131#issuecomment-676624533) directory and the [atlas](https://github.com/nim-lang/atlas) package cloner.
## Continuous Integration
### A simple example using GitHub Actions:
```yaml
name: Build
on:
push:
paths-ignore:
- README.md
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
jobs:
build:
name: Test
runs-on: ${{ matrix.os }}
matrix:
include:
# Test against stable Nim builds on linux
- os: ubuntu-latest
nim-version: latest:2.2
- os: ubuntu-latest
nim-version: latest:1.6
# Test against unstable nightly Nim builds on macos x64 (faster than building from source)
- os: macos-latest
nim-version: ref:version-2-2
- os: macos-latest
nim-version: ref:version-1-6
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Install Nim
uses: asdf-vm/actions/install@v4
with:
tool_versions: |
nim ${{ matrix.nim-version }}
- name: Run tests
run: |
asdf set nim ${{ matrix.nim-version }}
nimble develop -y
nimble test
nimble examples
```
### Continuous Integration on Non-x86 Architectures
Using [uraimo/run-on-arch-action](https://github.com/uraimo/run-on-arch-action):
```yaml
name: Build
on:
push:
paths-ignore:
- README.md
jobs:
test_non_x86:
name: Test nim-${{ matrix.nim-version }} / debian-buster / ${{ matrix.arch }}
strategy:
fail-fast: false
matrix:
include:
- nim-version: ref:version-2-2
arch: armv7
- nim-version: ref:version-1-6
arch: aarch64
runs-on: ubuntu-latest
steps:
- name: Checkout Nim project
uses: actions/checkout@v4
- uses: uraimo/run-on-arch-action@v3
name: Install Nim & run tests
with:
arch: ${{ matrix.arch }}
distro: bookworm
dockerRunArgs: |
--volume "${HOME}/.cache:/root/.cache"
--volume "${GITHUB_WORKSPACE}:/workspace"
setup: mkdir -p "${HOME}/.cache"
shell: /usr/bin/env bash
install: |
set -uexo pipefail
# Add Debian backports repository for newer Golang versions
cat >/etc/apt/sources.list.d/debian-backports.sources </asdf-nim.git ~/.asdf/plugins/nim
```
### Testing
This project uses [bats](https://github.com/bats-core/bats-core) for unit testing. Please follow existing patterns and add unit tests for your changeset. Dev dependencies for unit tests are installed via:
```shell
cd ~/.asdf/plugins/nim
npm install --include=dev
```
Run tests with:
```sh
npm run test
```
#### Test Performance Optimization
For faster local development, you can skip slow integration tests:
```sh
# Run only fast unit tests (~60s)
ASDF_NIM_SKIP_INTEGRATION=1 npm run test
# Run all tests including integration tests (~5-10 min)
npm run test
```
**Test Types:**
- **Unit tests** (`test/utils.bats`): Fast, mocked, test individual functions
- **Integration tests** (`test/integration.bats`): Slow, install real Nim versions
**CI Caching:** Integration tests cache Nim installations between runs for speed.
### Linting
This project uses [pre-commit](https://pre-commit.com/) to auto-format code. Please ensure your changeset passes linting. Install and enable pre-commit with:
```sh
pip install pre-commit
pre-commit install
```