mirror of
https://github.com/nim-lang/Nim.git
synced 2025-12-30 09:54:49 +00:00
139 lines
3.9 KiB
ReStructuredText
139 lines
3.9 KiB
ReStructuredText
================================
|
|
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"
|