nimlink

A simple and efficient tool for linking Nim packages for local development.

Problem

Working with local Nim packages should be simple, but often involves tedious manual steps:

• nimble develop doesn't respect srcDir in .nimble files
• Creating symlinks manually is error-prone and boring
• Editing nim.cfg files by hand is unnecessary work

Solution

nimlink automates these tedious tasks:

1. Tracks your local packages in a simple registry
2. Creates symlinks automatically with a single command
3. Updates nim.cfg files for you to ensure imports work
4. Makes everything "just work" so you can focus on coding

No more manually creating symlinks. No more editing config files. Just register once, install anywhere, and get back to writing Nim.

Installation

# Clone the repository
git clone https://github.com/yourusername/nimlink
cd nimlink

# Build it
nim c -d:release nimlink.nim

# Move it to your PATH
cp nimlink ~/.local/bin/ # or another directory in your PATH

Basic Usage

# Register the current package
cd /path/to/your/package
nimlink

# List registered packages
nimlink list  # or: nimlink l

# Install a package in your project
cd /path/to/your/project
nimlink install package_name  # or: nimlink i package_name

# Install without symlinks (direct mode)
nimlink install package_name -d  # or: nimlink i package_name --direct

# Uninstall a package
nimlink uninstall package_name  # or: nimlink u package_name

# Remove a package from the registry
nimlink remove package_name  # or: nimlink rm package_name

Commands

How It Works

1. Registration: When you run nimlink in a package directory:
2. Detects the package name from the .nimble file
3. Extracts srcDir if present

4. Stores the information in ~/.nimlink

5. Installation: When you run nimlink i package_name:

6. Creates a nimlinks/ directory in your project
7. Creates a symlink from the package source to nimlinks/package_name/

8. Adds --path="nimlinks/package_name" to your project's nim.cfg

9. Direct Mode: When you run nimlink i package_name -d:

10. Skips creating symlinks entirely
11. Adds the absolute path directly to nim.cfg: --path="/path/to/package/src"

12. Great for situations where symlinks are problematic

13. Importing: In your code:

14. Use import package_name from anywhere in your project
15. All changes to the source package are immediately available

Configuration

You can customize the links directory name with an environment variable:

export NIMLINK_DIR="vendor"  # Use "vendor" instead of "nimlinks"

Examples

Developing a library and an application together

# Register your library
cd ~/projects/mylibrary
nimlink

# Link it in your application (using shorthand)
cd ~/projects/myapp
nimlink i mylibrary

# Now in your application code
# You can use: import mylibrary
# Even from subdirectories like tests/

Working with multiple libraries (with direct paths)

# Register all your libraries
cd ~/projects/lib1
nimlink
cd ~/projects/lib2
nimlink

# Link them in your project without symlinks (using shorthand)
cd ~/projects/myproject
nimlink i lib1 -d
nimlink i lib2 -d

# Use them in your code
# import lib1
# import lib2

Requirements

• pkg/colors (install with nimble install colors)

License

MIT