# nimscript

Dark Mode

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs

Search:

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

    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

    version: string

  Nimble support: The package's version. Source Edit

    author: string

  Nimble support: The package's author. Source Edit

    description: string

  Nimble support: The package's description. Source Edit

    license: string

  Nimble support: The package's license. Source Edit

    srcDir: string

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

    binDir: string

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

    backend: string

  Nimble support: The package's backend. Source Edit

    skipDirs: seq[string] = @[]

  Nimble metadata. Source Edit

    skipFiles: seq[string] = @[]

  Nimble metadata. Source Edit

    skipExt: seq[string] = @[]

  Nimble metadata. Source Edit

    installDirs: seq[string] = @[]

  Nimble metadata. Source Edit

    installFiles: seq[string] = @[]

  Nimble metadata. Source Edit

    installExt: seq[string] = @[]

  Nimble metadata. Source Edit

    bin: seq[string] = @[]

  Nimble metadata. Source Edit

    requiresData: seq[string] = @[]

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

# Consts

    buildOS: string = ""

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

    buildCPU: string = ""

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

# Procs

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

  Retrieves the current working directory. Source Edit

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

  Retrieves the `i`'th command line parameter. Source Edit

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

  Retrieves the number of command line parameters. Source Edit

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

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

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

  Disables or enables a specific warning. Source Edit

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

  Disables or enables a specific hint. Source Edit

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

  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!

  Example:

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

  Source Edit

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

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

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

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

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

  Compares `a` and `b` ignoring case. Source Edit

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

  Retrieves the environment variable of name `key`. Source Edit

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

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

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

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

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

  Deletes the environment variable named `key`. Source Edit

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

  Checks if the file exists. Source Edit

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

  Checks if the directory `dir` exists. Source Edit

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

  Returns the currently running nim or nimble executable. Source Edit

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

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

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

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

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

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

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

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

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

  Removes the directory `dir`. Source Edit

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

  Removes the `file`. Source Edit

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

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

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

  Moves the file `from` to `to`. Source Edit

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

  Moves the dir `from` to `to`. Source Edit

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

  Copies the file `from` to `to`. Source Edit

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

  Copies the dir `from` to `to`. Source Edit

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

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

  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].}

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

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

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

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

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

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

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

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

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

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

  Retrieves the location of 'nimcache'. Source Edit

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

  Retrieves the name of the current project Source Edit

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

  Retrieves the absolute directory of the current project Source Edit

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

  Retrieves the absolute path of the current project Source Edit

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

  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 cd(dir: string) {...}{.raises: [OSError], tags: [].}

  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 findExe(bin: string): string {...}{.raises: [], tags: [].}

  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 cppDefine(define: string) {...}{.raises: [], tags: [].}

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

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

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

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

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

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

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

# Templates

    template existsFile(args: varargs[untyped]): untyped {...}{.
        deprecated: "use fileExists".}

  Deprecated: use fileExists
  Source Edit

    template existsDir(args: varargs[untyped]): untyped {...}{.
        deprecated: "use dirExists".}

  Deprecated: use dirExists
  Source Edit

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

  A shortcut for `switch(astToStr(key), astToStr(val))`. Source Edit

    template `--`(key: untyped)

  A shortcut for `switch(astToStr(key)`. 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:

      withDir "foo":
        # inside foo
      #back to last dir

  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