# system/nimscript

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
Source Edit

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