Strictly speaking, NimScript is the subset of Nim that can be evaluated by Nim's builtin virtual machine (VM). This VM is used for Nim's compiletime function evaluation features, but also replaces Nim's existing configuration system.

So instead of a myproject.nim.cfg configuration file, you can use a myproject.nims file that simply contains Nim code controlling the compilation process.

The VM cannot deal with importc, the FFI is not available, so there are not many stdlib modules that you can use with Nim's VM. However, the following modules are available:

The system module in NimScript mode additionally supports these operations: nimscript.

NimScript as a configuration file

What is x.y.key = "value" in the configuration file becomes switch("x.y.key", "value"). --option is switch("option"). The system module also exports 2 -- templates for convenience:

# is the same as:

NimScript as a build tool

The task template that the system module defines allows a NimScript file to be used as a build tool. The following exampled defines a task build that is an alias for the c command:

task build, "builds an example":
  setCommand "c"

In fact, as a convention the following tasks should be available:

buildBuild the project with the required backend (c, cpp or js).
testsRuns the tests belonging to the project.
benchRuns benchmarks belonging to the project.

If the task runs an external command via exec it should afterwards call setCommand "nop" to tell the Nim compiler that nothing else needs to be done:

task tests, "test regular expressions":
  exec "nim c -r tests"
  setCommand "nop"

Nimble integration

A project.nims file can also be used as an alternative to a project.nimble file to specify the meta information (for example, author, description) and dependencies of a Nimble package. This means you can easily have platform specific dependencies:

version = "1.0"
author = "The green goo."
description = "Lexer generation and regex implementation for Nim."
license = "MIT"

when defined(windows):
  requires "oldwinapi >= 1.0"
  requires "gtk2 >= 1.0"

Standalone NimScript

NimScript can also be used directly as a portable replacement for Bash and Batch files. Use nim e myscript.nims to run myscript.nims. For example, installation of Nimble is done with this simple script:

mode = ScriptMode.Verbose

var id = 0
while dirExists("nimble" & $id):
  inc id

exec "git clone nimble" & $id

withDir "nimble" & $id & "/src":
  exec "nim c nimble"

mvFile "nimble" & $id & "/src/nimble".toExe, "bin/nimble".toExe