system/nimscript

To learn about scripting in Nim see NimScript

Types

ScriptMode {.pure.} = enum
  Silent,                   ## Be silent.
  Verbose,                  ## Be verbose.
  Whatif                     ## Do not run commands, instead just echo what
                             ## would have been done.

Controls the behaviour of the script. Source Edit

Vars

author: string

Nimble support: The package's author. Source Edit

backend: string

Nimble support: The package's backend. Source Edit

bin: seq[string] = @[]

Source Edit

binDir: string

Nimble support: The package's binary directory. Source Edit

description: string

Nimble support: The package's description. Source Edit

installDirs: seq[string] = @[]

Source Edit

installExt: seq[string] = @[]

Source Edit

installFiles: seq[string] = @[]

Source Edit

license: string

Nimble support: The package's license. Source Edit

mode: ScriptMode

Set this to influence how mkDir, rmDir, rmFile etc. behave Source Edit

packageName = ""

Nimble support: Set this to the package name. It is usually not required to do that, nims' filename is the default. Source Edit

requiresData: seq[string] = @[]

Exposes the list of requirements for read and write accesses. Source Edit

skipDirs: seq[string] = @[]

Source Edit

skipExt: seq[string] = @[]

Source Edit

skipFiles: seq[string] = @[]

Source Edit

srcDir: string

Nimble support: The package's source directory. Source Edit

version: string

Nimble support: The package's version. Source Edit

Consts

buildCPU {.magic: "BuildCPU".}: string = ""

The CPU this build is running on. Can be different from system.hostCPU for cross compilations. Source Edit

buildOS {.magic: "BuildOS".}: string = ""

The OS this build is running on. Can be different from system.hostOS for cross compilations. Source Edit

Procs

proc cd(dir: string) {....raises: [OSError], tags: [], forbids: [].}

Changes the current directory.

The change is permanent for the rest of the execution, since this is just a shortcut for os.setCurrentDir() . Use the withDir() template if you want to perform a temporary change only.

Source Edit

proc cmpic(a, b: string): int {....raises: [], tags: [], forbids: [].}

Compares a and b ignoring case. Source Edit

proc cpDir(from, to: string) {....raises: [OSError],
                               tags: [ReadIOEffect, WriteIOEffect], forbids: [].}

Copies the dir from to to. Source Edit

proc cpFile(from, to: string) {....raises: [OSError],
                                tags: [ReadIOEffect, WriteIOEffect], forbids: [].}

Copies the file from to to. Source Edit

proc cppDefine(define: string) {....raises: [], tags: [], forbids: [].}

tell Nim that define is a C preprocessor #define and so always needs to be mangled. Source Edit

proc delEnv(key: string) {....tags: [WriteIOEffect], raises: [], forbids: [].}

Deletes the environment variable named key. Source Edit

proc dirExists(dir: string): bool {....tags: [ReadIOEffect], raises: [],
                                    forbids: [].}

Checks if the directory dir exists. Source Edit

proc exec(command: string) {....raises: [OSError],
                             tags: [ExecIOEffect, WriteIOEffect], forbids: [].}

Executes an external process. If the external process terminates with a non-zero exit code, an OSError exception is raised. The command is executed relative to the current source path.

Note: If you need a version of exec that returns the exit code and text output of the command, you can use system.gorgeEx.

Source Edit

proc exec(command: string; input: string; cache = "") {....raises: [OSError],
    tags: [ExecIOEffect, WriteIOEffect], forbids: [].}

Executes an external process. If the external process terminates with a non-zero exit code, an OSError exception is raised.

Warning: This version of exec is executed relative to the nimscript module path, which affects how the command resolves relative paths. Thus it is generally better to use gorgeEx directly when you need more control over the execution environment or when working with commands that deal with relative paths.

Source Edit

proc exists(key: string): bool {....raises: [], tags: [], forbids: [].}

Checks for the existence of a configuration 'key' like 'gcc.options.always'. Source Edit

proc existsEnv(key: string): bool {....tags: [ReadIOEffect], raises: [],
                                    forbids: [].}

Checks for the existence of an environment variable named key. Source Edit

proc fileExists(filename: string): bool {....tags: [ReadIOEffect], raises: [],
    forbids: [].}

Checks if the file exists. Source Edit

proc findExe(bin: string): string {....raises: [], tags: [], forbids: [].}

Searches for bin in the current working directory and then in directories listed in the PATH environment variable. Returns "" if the exe cannot be found. Source Edit

proc get(key: string): string {....raises: [], tags: [], forbids: [].}

Retrieves a configuration 'key' like 'gcc.options.always'. Source Edit

proc getCommand(): string {....raises: [], tags: [], forbids: [].}

Gets the Nim command that the compiler has been invoked with, for example "c", "js", "build", "help". Source Edit

proc getCurrentDir(): string {....raises: [], tags: [], forbids: [].}

Retrieves the current working directory. Source Edit

proc getEnv(key: string; default = ""): string {....tags: [ReadIOEffect],
    raises: [], forbids: [].}

Retrieves the environment variable of name key. Source Edit

proc hint(name: string; val: bool) {....raises: [], tags: [], forbids: [].}

Disables or enables a specific hint. Source Edit

proc listDirs(dir: string): seq[string] {....raises: [OSError],
    tags: [ReadIOEffect], forbids: [].}

Lists all the subdirectories (non-recursively) in the directory dir. Source Edit

proc listFiles(dir: string): seq[string] {....raises: [OSError],
    tags: [ReadIOEffect], forbids: [].}

Lists all the files (non-recursively) in the directory dir. Source Edit

proc mkDir(dir: string) {....raises: [OSError], tags: [WriteIOEffect], forbids: [].}

Creates the directory dir including all necessary subdirectories. If the directory already exists, no error is raised. Source Edit

proc mvDir(from, to: string) {....raises: [OSError],
                               tags: [ReadIOEffect, WriteIOEffect], forbids: [].}

Moves the dir from to to. Source Edit

proc mvFile(from, to: string) {....raises: [OSError],
                                tags: [ReadIOEffect, WriteIOEffect], forbids: [].}

Moves the file from to to. Source Edit

proc nimcacheDir(): string {....raises: [], tags: [], forbids: [].}

Retrieves the location of 'nimcache'. Source Edit

proc paramCount(): int {....raises: [], tags: [], forbids: [].}

Retrieves the number of command line parameters. Source Edit

proc paramStr(i: int): string {....raises: [], tags: [], forbids: [].}

Retrieves the i'th command line parameter. Source Edit

proc patchFile(package, filename, replacement: string) {....raises: [], tags: [],
    forbids: [].}

Overrides the location of a given file belonging to the passed package. If the replacement is not an absolute path, the path is interpreted to be local to the Nimscript file that contains the call to patchFile, Nim's --path is not used at all to resolve the filename! The compiler also performs path substitution on replacement.

Example:

patchFile("stdlib", "asyncdispatch", "patches/replacement")

Source Edit

proc projectDir(): string {....raises: [], tags: [], forbids: [].}

Retrieves the absolute directory of the current project Source Edit

proc projectName(): string {....raises: [], tags: [], forbids: [].}

Retrieves the name of the current project Source Edit

proc projectPath(): string {....raises: [], tags: [], forbids: [].}

Retrieves the absolute path of the current project Source Edit

proc put(key, value: string) {....raises: [], tags: [], forbids: [].}

Sets a configuration 'key' like 'gcc.options.always' to its value. Source Edit

proc putEnv(key, val: string) {....tags: [WriteIOEffect], raises: [], forbids: [].}

Sets the value of the environment variable named key to val. Source Edit

proc readAllFromStdin(): string {....raises: [IOError], tags: [ReadIOEffect],
                                  forbids: [].}

Reads all data from stdin - blocks until EOF which happens when stdin is closed Source Edit

proc readLineFromStdin(): string {....raises: [IOError], tags: [ReadIOEffect],
                                   forbids: [].}

Reads a line of data from stdin - blocks until n or EOF which happens when stdin is closed Source Edit

proc requires(deps: varargs[string]) {....raises: [], tags: [], forbids: [].}

Nimble support: Call this to set the list of requirements of your Nimble package. Source Edit

proc rmDir(dir: string; checkDir = false) {....raises: [OSError],
    tags: [ReadIOEffect, WriteIOEffect], forbids: [].}

Removes the directory dir. Source Edit

proc rmFile(file: string) {....raises: [OSError],
                            tags: [ReadIOEffect, WriteIOEffect], forbids: [].}

Removes the file. Source Edit

proc selfExe(): string {....deprecated: "Deprecated since v1.7; Use getCurrentCompilerExe",
                         raises: [], tags: [], forbids: [].}

Deprecated: Deprecated since v1.7; Use getCurrentCompilerExe

Returns the currently running nim or nimble executable. Source Edit

proc selfExec(command: string) {....raises: [OSError],
                                 tags: [ExecIOEffect, WriteIOEffect],
                                 forbids: [].}

Executes an external command with the current nim/nimble executable. Command must not contain the "nim " part. Source Edit

proc setCommand(cmd: string; project = "") {....raises: [], tags: [], forbids: [].}

Sets the Nim command that should be continued with after this Nimscript has finished. Source Edit

proc switch(key: string; val = "") {....raises: [], tags: [], forbids: [].}

Sets a Nim compiler command line switch, for example switch("checks", "on"). Source Edit

proc thisDir(): string {....raises: [], tags: [], forbids: [].}

Retrieves the directory of the current nims script file. Its path is obtained via currentSourcePath (although, currently, currentSourcePath resolves symlinks, unlike thisDir). Source Edit

proc toDll(filename: string): string {....raises: [], tags: [], forbids: [].}

On Windows adds ".dll" to filename, on Posix produces "lib$filename.so". Source Edit

proc toExe(filename: string): string {....raises: [], tags: [], forbids: [].}

On Windows adds ".exe" to filename, else returns filename unmodified. Source Edit

proc warning(name: string; val: bool) {....raises: [], tags: [], forbids: [].}

Disables or enables a specific warning. Source Edit

Templates

template `--`(key, val: untyped)

A shortcut for switch Example:

--path:somePath # same as switch("path", "somePath")
--path:"someOtherPath" # same as switch("path", "someOtherPath")
--hint:"[Conf]:off" # same as switch("hint", "[Conf]:off")

Source Edit

template `--`(key: untyped)

A shortcut for switch Example:

--listCmd # same as switch("listCmd")

Source Edit

template task(name: untyped; description: string; body: untyped): untyped

Defines a task. Hidden tasks are supported via an empty description.

Example:

task build, "default build is via the C backend":
  setCommand "c"

For a task named foo, this template generates a proc named fooTask. This is useful if you need to call one task in another in your Nimscript.

Example:

task foo, "foo":        # > nim foo
  echo "Running foo"    # Running foo

task bar, "bar":        # > nim bar
  echo "Running bar"    # Running bar
  fooTask()             # Running foo

Source Edit

template withDir(dir: string; body: untyped): untyped

Changes the current directory temporarily.

If you need a permanent change, use the cd() proc. Usage example:

# inside /some/path/
withDir "foo":
  # move to /some/path/foo/
# back in /some/path/

Source Edit