1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
================================
NimScript
================================
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:
* `macros <macros.html>`_
* `ospaths <ospaths.html>`_
* `strutils <strutils.html>`_
* `math <math.html>`_
* `distros <distros.html>`_
In addition to the standard Nim syntax (`system <system.html>`_
module), NimScripts support the procs and templates defined in the
`nimscript <nimscript.html>`_ 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:
.. code-block:: nim
# command-line: --opt:size
switch("opt", "size")
# command-line: --define:foo or -d:foo
switch("define", "foo")
# command-line: --forceBuild
switch("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:
.. code-block:: nim
--opt:size
--define:foo
--forceBuild
**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:
.. code-block:: nim
task build, "builds an example":
setCommand "c"
In fact, as a convention the following tasks should be available:
========= ===================================================
Task Description
========= ===================================================
``build`` Build the project with the required
backend (``c``, ``cpp`` or ``js``).
``tests`` Runs the tests belonging to the project.
``bench`` Runs 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:
.. code-block:: nim
task tests, "test regular expressions":
exec "nim c -r tests"
setCommand "nop"
Look at the module `distros <distros.html>`_ for some support of the
OS's native package managers.
Nimble integration
==================
See the `Nimble readme <https://github.com/nim-lang/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:
.. code-block:: nim
mode = ScriptMode.Verbose
var id = 0
while dirExists("nimble" & $id):
inc id
exec "git clone https://github.com/nim-lang/nimble.git 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``:
.. code-block:: nim
#!/usr/bin/env nim
mode = ScriptMode.Silent
echo "hello world"
|