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.

You can use a <myproject>.nims file that simply contains Nim code controlling the compilation process. For a directory wide configuration, use config.nims instead of <myproject>.nims.

The VM cannot deal with importc because the FFI is not available. So the stdlib modules using importc cannot be used with Nim's VM. However, at least the following modules are available:

In addition to the standard Nim syntax (system module), NimScripts support the procs and templates defined in the nimscript module too.

NimScript as a configuration file

A command-line switch --FOO is written as switch("FOO") in NimScript. Similarly, command-line --FOO:VAL translates to switch("FOO", "VAL").

Here are few examples of using the switch proc:

# command-line: --opt:size
switch("opt", "size")
# command-line: --define:foo or -d:foo
switch("define", "foo")
# command-line: --forceBuild

NimScripts also support -- templates for convenience, which look like command-line switches written as-is in the NimScript file. So the above example can be rewritten as:


Note: In general, the define switches can also be set in NimScripts using switch or --, as shown in above examples. Only the release define (-d:release) cannot be set in NimScripts.

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 example 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"

Look at the module distros for some support of the OS's native package managers.

Nimble integration

See the Nimble readme for more information.

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 could be accomplished 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

You can also use the shebang #!/usr/bin/env nim, as long as your filename ends with .nims:

#!/usr/bin/env nim
mode = ScriptMode.Silent

echo "hello world"