jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

follow-up #17692: more inline syntax highlighting (#17837)

Browse source
This commit is contained in:
Andrey Makarov 2021-04-29 18:16:14 +03:00 • committed by GitHub
commit e61381a293
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 287 additions and 181 deletions
Download patch file Download diff file Expand all files Collapse all files

5
doc/apis.rst
View file

@ -1,9 +1,10 @@
.. default-role:: code
================= =================
API naming design API naming design
================= =================
.. default-role:: code
.. include:: rstcommon.rst
The API is designed to be **easy to use** and consistent. Ease of use is The API is designed to be **easy to use** and consistent. Ease of use is
measured by the number of calls to achieve a concrete high-level action. measured by the number of calls to achieve a concrete high-level action.

125
doc/backends.rst
View file

@ -1,5 +1,3 @@
.. default-role:: code
================================ ================================
Nim Backend Integration Nim Backend Integration
================================ ================================
@ -7,6 +5,10 @@
:Author: Puppet Master :Author: Puppet Master
:Version: |nimversion| :Version: |nimversion|
.. default-role:: code
.. include:: rstcommon.rst
.. no syntax highlighting here by default:
.. contents:: .. contents::
"Heresy grows from idleness." -- Unknown. "Heresy grows from idleness." -- Unknown.
@ -15,8 +17,9 @@ Introduction
============ ============
The `Nim Compiler User Guide <nimc.html>`_ documents the typical The `Nim Compiler User Guide <nimc.html>`_ documents the typical
compiler invocation, using the `compile` or `c` command to transform a compiler invocation, using the `compile`:option:
`.nim` file into one or more `.c` files which are then compiled with the or `c`:option: command to transform a
``.nim`` file into one or more ``.c`` files which are then compiled with the
platform's C compiler into a static binary. However, there are other commands platform's C compiler into a static binary. However, there are other commands
to compile to C++, Objective-C, or JavaScript. This document tries to to compile to C++, Objective-C, or JavaScript. This document tries to
concentrate in a single place all the backend and interfacing options. concentrate in a single place all the backend and interfacing options.
@ -25,7 +28,7 @@ The Nim compiler supports mainly two backend families: the C, C++ and
Objective-C targets and the JavaScript target. `The C like targets Objective-C targets and the JavaScript target. `The C like targets
<#backends-the-c-like-targets>`_ creates source files that can be compiled <#backends-the-c-like-targets>`_ creates source files that can be compiled
into a library or a final executable. `The JavaScript target into a library or a final executable. `The JavaScript target
<#backends-the-javascript-target>`_ can generate a `.js` file which you <#backends-the-javascript-target>`_ can generate a ``.js`` file which you
reference from an HTML file or create a `standalone Node.js program reference from an HTML file or create a `standalone Node.js program
<http://nodejs.org>`_. <http://nodejs.org>`_.
@ -47,15 +50,17 @@ The commands to compile to either C, C++ or Objective-C are:
//compileToOC, objc compile project to Objective C code //compileToOC, objc compile project to Objective C code
The most significant difference between these commands is that if you look The most significant difference between these commands is that if you look
into the `nimcache` directory you will find `.c`, `.cpp` or `.m` into the ``nimcache`` directory you will find ``.c``, ``.cpp`` or ``.m``
files, other than that all of them will produce a native binary for your files, other than that all of them will produce a native binary for your
project. This allows you to take the generated code and place it directly project. This allows you to take the generated code and place it directly
into a project using any of these languages. Here are some typical command- into a project using any of these languages. Here are some typical command-
line invocations:: line invocations:
$ nim c hallo.nim .. code:: cmd
$ nim cpp hallo.nim
$ nim objc hallo.nim nim c hallo.nim
nim cpp hallo.nim
nim objc hallo.nim
The compiler commands select the target backend, but if needed you can The compiler commands select the target backend, but if needed you can
`specify additional switches for cross-compilation `specify additional switches for cross-compilation
@ -66,11 +71,11 @@ or compiler/linker commands.
The JavaScript target The JavaScript target
--------------------- ---------------------
Nim can also generate `JavaScript`:idx: code through the `js` command. Nim can also generate `JavaScript`:idx: code through the `js`:option: command.
Nim targets JavaScript 1.5 which is supported by any widely used browser. Nim targets JavaScript 1.5 which is supported by any widely used browser.
Since JavaScript does not have a portable means to include another module, Since JavaScript does not have a portable means to include another module,
Nim just generates a long `.js` file. Nim just generates a long ``.js`` file.
Features or modules that the JavaScript platform does not support are not Features or modules that the JavaScript platform does not support are not
available. This includes: available. This includes:
@ -88,10 +93,12 @@ To compensate, the standard library has modules `catered to the JS backend
and more support will come in the future (for instance, Node.js bindings and more support will come in the future (for instance, Node.js bindings
to get OS info). to get OS info).
To compile a Nim module into a `.js` file use the `js` command; the To compile a Nim module into a ``.js`` file use the `js`:option: command; the
default is a `.js` file that is supposed to be referenced in an `.html` default is a ``.js`` file that is supposed to be referenced in an ``.html``
file. However, you can also run the code with `nodejs`:idx: file. However, you can also run the code with `nodejs`:idx:
(`<http://nodejs.org>`_):: (`<http://nodejs.org>`_):
.. code:: cmd
nim js -d:nodejs -r examples/hallo.nim nim js -d:nodejs -r examples/hallo.nim
@ -150,7 +157,7 @@ interface.
C invocation example C invocation example
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~
Create a `logic.c` file with the following content: Create a ``logic.c`` file with the following content:
.. code-block:: c .. code-block:: c
int addTwoIntegers(int a, int b) int addTwoIntegers(int a, int b)
@ -158,7 +165,7 @@ Create a `logic.c` file with the following content:
return a + b; return a + b;
} }
Create a `calculator.nim` file with the following content: Create a ``calculator.nim`` file with the following content:
.. code-block:: nim .. code-block:: nim
@ -168,26 +175,28 @@ Create a `calculator.nim` file with the following content:
when isMainModule: when isMainModule:
echo addTwoIntegers(3, 7) echo addTwoIntegers(3, 7)
With these two files in place, you can run `nim c -r calculator.nim` and With these two files in place, you can run `nim c -r calculator.nim`:cmd: and
the Nim compiler will compile the `logic.c` file in addition to the Nim compiler will compile the ``logic.c`` file in addition to
`calculator.nim` and link both into an executable, which outputs `10` when ``calculator.nim`` and link both into an executable, which outputs `10` when
run. Another way to link the C file statically and get the same effect would run. Another way to link the C file statically and get the same effect would
be to remove the line with the `compile` pragma and run the following typical be to remove the line with the `compile` pragma and run the following
Unix commands:: typical Unix commands:
$ gcc -c logic.c .. code:: cmd
$ ar rvs mylib.a logic.o
$ nim c --passL:mylib.a -r calculator.nim
Just like in this example we pass the path to the `mylib.a` library (and we gcc -c logic.c
could as well pass `logic.o`) we could be passing switches to link any other ar rvs mylib.a logic.o
nim c --passL:mylib.a -r calculator.nim
Just like in this example we pass the path to the ``mylib.a`` library (and we
could as well pass ``logic.o``) we could be passing switches to link any other
static C library. static C library.
JavaScript invocation example JavaScript invocation example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Create a `host.html` file with the following content: Create a ``host.html`` file with the following content:
.. code-block:: .. code-block::
@ -201,7 +210,7 @@ Create a `host.html` file with the following content:
<script type="text/javascript" src="calculator.js"></script> <script type="text/javascript" src="calculator.js"></script>
</body></html> </body></html>
Create a `calculator.nim` file with the following content (or reuse the one Create a ``calculator.nim`` file with the following content (or reuse the one
from the previous section): from the previous section):
.. code-block:: nim .. code-block:: nim
@ -212,7 +221,7 @@ from the previous section):
echo addTwoIntegers(3, 7) echo addTwoIntegers(3, 7)
Compile the Nim code to JavaScript with `nim js -o:calculator.js Compile the Nim code to JavaScript with `nim js -o:calculator.js
calculator.nim` and open `host.html` in a browser. If the browser supports calculator.nim`:cmd: and open ``host.html`` in a browser. If the browser supports
javascript, you should see the value `10` in the browser's console. Use the javascript, you should see the value `10` in the browser's console. Use the
`dom module <dom.html>`_ for specific DOM querying and modification procs `dom module <dom.html>`_ for specific DOM querying and modification procs
or take a look at `karax <https://github.com/pragmagic/karax>`_ for how to or take a look at `karax <https://github.com/pragmagic/karax>`_ for how to
@ -237,7 +246,7 @@ Also, C code requires you to specify a forward declaration for functions or
the compiler will assume certain types for the return value and parameters the compiler will assume certain types for the return value and parameters
which will likely make your program crash at runtime. which will likely make your program crash at runtime.
The Nim compiler can generate a C interface header through the `--header` The Nim compiler can generate a C interface header through the `--header`:option:
command-line switch. The generated header will contain all the exported command-line switch. The generated header will contain all the exported
symbols and the `NimMain` proc which you need to call before any other symbols and the `NimMain` proc which you need to call before any other
Nim code. Nim code.
@ -246,7 +255,7 @@ Nim code.
Nim invocation example from C Nim invocation example from C
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Create a `fib.nim` file with the following content: Create a ``fib.nim`` file with the following content:
.. code-block:: nim .. code-block:: nim
@ -256,7 +265,7 @@ Create a `fib.nim` file with the following content:
else: else:
result = fib(a - 1) + fib(a - 2) result = fib(a - 1) + fib(a - 2)
Create a `maths.c` file with the following content: Create a ``maths.c`` file with the following content:
.. code-block:: c .. code-block:: c
@ -273,36 +282,40 @@ Create a `maths.c` file with the following content:
Now you can run the following Unix like commands to first generate C sources Now you can run the following Unix like commands to first generate C sources
from the Nim code, then link them into a static binary along your main C from the Nim code, then link them into a static binary along your main C
program:: program:
$ nim c --noMain --noLinking --header:fib.h fib.nim .. code:: cmd
$ gcc -o m -I$HOME/.cache/nim/fib_d -Ipath/to/nim/lib $HOME/.cache/nim/fib_d/*.c maths.c
nim c --noMain --noLinking --header:fib.h fib.nim
gcc -o m -I$HOME/.cache/nim/fib_d -Ipath/to/nim/lib $HOME/.cache/nim/fib_d/*.c maths.c
The first command runs the Nim compiler with three special options to avoid The first command runs the Nim compiler with three special options to avoid
generating a `main()` function in the generated files, avoid linking the generating a `main()`:c: function in the generated files, avoid linking the
object files into a final binary, and explicitly generate a header file for C object files into a final binary, and explicitly generate a header file for C
integration. All the generated files are placed into the `nimcache` integration. All the generated files are placed into the ``nimcache``
directory. That's why the next command compiles the `maths.c` source plus directory. That's why the next command compiles the ``maths.c`` source plus
all the `.c` files from `nimcache`. In addition to this path, you also all the ``.c`` files from ``nimcache``. In addition to this path, you also
have to tell the C compiler where to find Nim's `nimbase.h` header file. have to tell the C compiler where to find Nim's ``nimbase.h`` header file.
Instead of depending on the generation of the individual `.c` files you can Instead of depending on the generation of the individual ``.c`` files you can
also ask the Nim compiler to generate a statically linked library:: also ask the Nim compiler to generate a statically linked library:
$ nim c --app:staticLib --noMain --header fib.nim .. code:: cmd
$ gcc -o m -Inimcache -Ipath/to/nim/lib libfib.nim.a maths.c
nim c --app:staticLib --noMain --header fib.nim
gcc -o m -Inimcache -Ipath/to/nim/lib libfib.nim.a maths.c
The Nim compiler will handle linking the source files generated in the The Nim compiler will handle linking the source files generated in the
`nimcache` directory into the `libfib.nim.a` static library, which you can ``nimcache`` directory into the ``libfib.nim.a`` static library, which you can
then link into your C program. Note that these commands are generic and will then link into your C program. Note that these commands are generic and will
vary for each system. For instance, on Linux systems you will likely need to vary for each system. For instance, on Linux systems you will likely need to
use `-ldl` too to link in required dlopen functionality. use `-ldl`:option: too to link in required dlopen functionality.
Nim invocation example from JavaScript Nim invocation example from JavaScript
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Create a `mhost.html` file with the following content: Create a ``mhost.html`` file with the following content:
.. code-block:: .. code-block::
@ -313,7 +326,7 @@ Create a `mhost.html` file with the following content:
</script> </script>
</body></html> </body></html>
Create a `fib.nim` file with the following content (or reuse the one Create a ``fib.nim`` file with the following content (or reuse the one
from the previous section): from the previous section):
.. code-block:: nim .. code-block:: nim
@ -324,9 +337,9 @@ from the previous section):
else: else:
result = fib(a - 1) + fib(a - 2) result = fib(a - 1) + fib(a - 2)
Compile the Nim code to JavaScript with `nim js -o:fib.js fib.nim` and Compile the Nim code to JavaScript with `nim js -o:fib.js fib.nim`:cmd: and
open `mhost.html` in a browser. If the browser supports javascript, you open ``mhost.html`` in a browser. If the browser supports javascript, you
should see an alert box displaying the text `Fib for 9 is 34`. As mentioned should see an alert box displaying the text ``Fib for 9 is 34``. As mentioned
earlier, JavaScript doesn't require an initialization call to `NimMain` or earlier, JavaScript doesn't require an initialization call to `NimMain` or
a similar function and you can call the exported Nim proc directly. a similar function and you can call the exported Nim proc directly.
@ -337,7 +350,7 @@ Nimcache naming logic
The `nimcache`:idx: directory is generated during compilation and will hold The `nimcache`:idx: directory is generated during compilation and will hold
either temporary or final files depending on your backend target. The default either temporary or final files depending on your backend target. The default
name for the directory depends on the used backend and on your OS but you can name for the directory depends on the used backend and on your OS but you can
use the `--nimcache` `compiler switch use the `--nimcache`:option: `compiler switch
<nimc.html#compiler-usage-commandminusline-switches>`_ to change it. <nimc.html#compiler-usage-commandminusline-switches>`_ to change it.
@ -362,8 +375,8 @@ painless. Most C functions accepting a Nim string converted to a
`cstring` will likely not need to keep this string around and by the time `cstring` will likely not need to keep this string around and by the time
they return the string won't be needed anymore. However, for the rare cases they return the string won't be needed anymore. However, for the rare cases
where a Nim string has to be preserved and made available to the C backend where a Nim string has to be preserved and made available to the C backend
as a `cstring`, you will need to manually prevent the string data from being as a `cstring`, you will need to manually prevent the string data
freed with `GC_ref <system.html#GC_ref,string>`_ and `GC_unref from being freed with `GC_ref <system.html#GC_ref,string>`_ and `GC_unref
<system.html#GC_unref,string>`_. <system.html#GC_unref,string>`_.
A similar thing happens with C code invoking Nim code which returns a A similar thing happens with C code invoking Nim code which returns a
@ -399,7 +412,7 @@ Again, if you are wrapping a library which *mallocs* and *frees* data
structures, you need to expose the appropriate *free* function to Nim so structures, you need to expose the appropriate *free* function to Nim so
you can clean it up. And of course, once cleaned you should avoid accessing it you can clean it up. And of course, once cleaned you should avoid accessing it
from Nim (or C for that matter). Typically C data structures have their own from Nim (or C for that matter). Typically C data structures have their own
`malloc_structure` and `free_structure` specific functions, so wrapping `malloc_structure`:c: and `free_structure`:c: specific functions, so wrapping
these for the Nim side should be enough. these for the Nim side should be enough.

47
doc/manual.rst
View file

@ -127,9 +127,9 @@ compiler may instead choose to allow the program to die with a fatal error.
echo "invalid index" echo "invalid index"
The current implementation allows to switch between these different behaviors The current implementation allows to switch between these different behaviors
via ``--panics:on|off``. When panics are turned on, the program dies with a via `--panics:on|off`:option:. When panics are turned on, the program dies with a
panic, if they are turned off the runtime errors are turned into panic, if they are turned off the runtime errors are turned into
exceptions. The benefit of ``--panics:on`` is that it produces smaller binary exceptions. The benefit of `--panics:on`:option: is that it produces smaller binary
code and the compiler has more freedom to optimize the code. code and the compiler has more freedom to optimize the code.
An `unchecked runtime error`:idx: is an error that is not guaranteed to be An `unchecked runtime error`:idx: is an error that is not guaranteed to be
@ -678,7 +678,7 @@ defined here.)
These keywords are also operators: These keywords are also operators:
`and or not xor shl shr div mod in notin is isnot of as from`. `and or not xor shl shr div mod in notin is isnot of as from`.
`.`:tok: `=`:tok:, `:`:tok:, `::`:tok: are not available as general operators; they `.`:tok:, `=`:tok:, `:`:tok:, `::`:tok: are not available as general operators; they
are used for other notational purposes. are used for other notational purposes.
`*:` is as a special case treated as the two tokens `*`:tok: and `:`:tok: `*:` is as a special case treated as the two tokens `*`:tok: and `:`:tok:
@ -697,7 +697,7 @@ The following strings denote other tokens::
The `slice`:idx: operator `..`:tok: takes precedence over other tokens that The `slice`:idx: operator `..`:tok: takes precedence over other tokens that
contain a dot: `{..}`:tok: are the three tokens `{`:tok:, `..`:tok:, `}`:tok: contain a dot: `{..}` are the three tokens `{`:tok:, `..`:tok:, `}`:tok:
and not the two tokens `{.`:tok:, `.}`:tok:. and not the two tokens `{.`:tok:, `.}`:tok:.
@ -1460,7 +1460,7 @@ The notation `x[i]` can be used to access the i-th element of `x`.
Arrays are always bounds checked (statically or at runtime). These Arrays are always bounds checked (statically or at runtime). These
checks can be disabled via pragmas or invoking the compiler with the checks can be disabled via pragmas or invoking the compiler with the
``--boundChecks:off`` command-line switch. `--boundChecks:off`:option: command-line switch.
An array constructor can have explicit indexes for readability: An array constructor can have explicit indexes for readability:
@ -4093,7 +4093,7 @@ Multi-methods
-------------- --------------
**Note:** Starting from Nim 0.20, to use multi-methods one must explicitly pass **Note:** Starting from Nim 0.20, to use multi-methods one must explicitly pass
``--multimethods:on`` when compiling. `--multimethods:on`:option: when compiling.
In a multi-method, all parameters that have an object type are used for the In a multi-method, all parameters that have an object type are used for the
dispatching: dispatching:
@ -4805,7 +4805,7 @@ And so is:
The reason for this is that `DivByZeroDefect` inherits from `Defect` and The reason for this is that `DivByZeroDefect` inherits from `Defect` and
with ``--panics:on`` Defects become unrecoverable errors. with `--panics:on`:option: Defects become unrecoverable errors.
(Since version 1.4 of the language.) (Since version 1.4 of the language.)
@ -5604,7 +5604,7 @@ However, this means that the method call syntax is not available for
**Note**: The Nim compiler prior to version 1 was more lenient about this **Note**: The Nim compiler prior to version 1 was more lenient about this
requirement. Use the ``--useVersion:0.19`` switch for a transition period. requirement. Use the `--useVersion:0.19`:option: switch for a transition period.
@ -6960,7 +6960,7 @@ with the project:
{.compile: "myfile.cpp".} {.compile: "myfile.cpp".}
**Note**: Nim computes a SHA1 checksum and only recompiles the file if it **Note**: Nim computes a SHA1 checksum and only recompiles the file if it
has changed. One can use the ``-f`` command-line option to force has changed. One can use the `-f`:option: command-line option to force
the recompilation of the file. the recompilation of the file.
Since 1.4 the `compile` pragma is also available with this syntax: Since 1.4 the `compile` pragma is also available with this syntax:
@ -6983,7 +6983,7 @@ The `link` pragma can be used to link an additional file with the project:
PassC pragma PassC pragma
------------ ------------
The `passc` pragma can be used to pass additional parameters to the C The `passc` pragma can be used to pass additional parameters to the C
compiler like one would using the command-line switch ``--passc``: compiler like one would using the command-line switch `--passc`:option:\:
.. code-block:: Nim .. code-block:: Nim
{.passc: "-Wall -Werror".} {.passc: "-Wall -Werror".}
@ -7011,7 +7011,7 @@ the pragma resides in:
PassL pragma PassL pragma
------------ ------------
The `passL` pragma can be used to pass additional parameters to the linker The `passL` pragma can be used to pass additional parameters to the linker
like one would be using the command-line switch ``--passL``: like one would be using the command-line switch `--passL`:option:\:
.. code-block:: Nim .. code-block:: Nim
{.passL: "-lSDLmain -lSDL".} {.passL: "-lSDLmain -lSDL".}
@ -7047,8 +7047,8 @@ Example:
embedsC() embedsC()
`nimbase.h` defines `NIM_EXTERNC` C macro that can be used for ``nimbase.h`` defines `NIM_EXTERNC`:c: C macro that can be used for
`extern "C"`:cpp: code to work with both `nim c` and `nim cpp`, e.g.: `extern "C"`:cpp: code to work with both `nim c`:cmd: and `nim cpp`:cmd:, e.g.:
.. code-block:: Nim .. code-block:: Nim
proc foobar() {.importc:"$1".} proc foobar() {.importc:"$1".}
@ -7124,7 +7124,7 @@ pragmas this allows *sloppy* interfacing with libraries written in C++:
proc run(device: IrrlichtDevice): bool {. proc run(device: IrrlichtDevice): bool {.
header: irr, importcpp: "#.run(@)".} header: irr, importcpp: "#.run(@)".}
The compiler needs to be told to generate C++ (command ``cpp``) for The compiler needs to be told to generate C++ (command `cpp`:option:) for
this to work. The conditional symbol `cpp` is defined when the compiler this to work. The conditional symbol `cpp` is defined when the compiler
emits C++ code. emits C++ code.
@ -7368,7 +7368,7 @@ allows *sloppy* interfacing with libraries written in Objective C:
g.greet(12, 34) g.greet(12, 34)
g.free() g.free()
The compiler needs to be told to generate Objective C (command ``objc``) for The compiler needs to be told to generate Objective C (command `objc`:option:) for
this to work. The conditional symbol ``objc`` is defined when the compiler this to work. The conditional symbol ``objc`` is defined when the compiler
emits Objective C code. emits Objective C code.
@ -7414,7 +7414,7 @@ will generate this code:
The `.cppNonPod` pragma should be used for non-POD `importcpp` types so that they The `.cppNonPod` pragma should be used for non-POD `importcpp` types so that they
work properly (in particular regarding constructor and destructor) for work properly (in particular regarding constructor and destructor) for
`.threadvar` variables. This requires ``--tlsEmulation:off``. `.threadvar` variables. This requires `--tlsEmulation:off`:option:.
.. code-block:: nim .. code-block:: nim
type Foo {.cppNonPod, importcpp, header: "funs.h".} = object type Foo {.cppNonPod, importcpp, header: "funs.h".} = object
@ -7458,12 +7458,13 @@ pragma description
:: ::
nim c -d:FooBar=42 foobar.nim nim c -d:FooBar=42 foobar.nim
In the above example, providing the ``-d`` flag causes the symbol In the above example, providing the `-d`:option: flag causes the symbol
`FooBar` to be overwritten at compile-time, printing out 42. If the `FooBar` to be overwritten at compile-time, printing out 42. If the
``-d:FooBar=42`` were to be omitted, the default value of 5 would be `-d:FooBar=42`:option: were to be omitted, the default value of 5 would be
used. To see if a value was provided, `defined(FooBar)` can be used. used. To see if a value was provided, `defined(FooBar)` can be used.
The syntax ``-d:flag`` is actually just a shortcut for ``-d:flag=true``. The syntax `-d:flag`:option: is actually just a shortcut for
`-d:flag=true`:option:.
User-defined pragmas User-defined pragmas
==================== ====================
@ -7800,7 +7801,7 @@ strings, because they are precompiled.
because of order of initialization problems. because of order of initialization problems.
**Note**: A `dynlib` import can be overridden with **Note**: A `dynlib` import can be overridden with
the ``--dynlibOverride:name`` command-line option. The the `--dynlibOverride:name`:option: command-line option. The
`Compiler User Guide <nimc.html>`_ contains further information. `Compiler User Guide <nimc.html>`_ contains further information.
@ -7815,14 +7816,14 @@ conjunction with the `exportc` pragma:
proc exportme(): int {.cdecl, exportc, dynlib.} proc exportme(): int {.cdecl, exportc, dynlib.}
This is only useful if the program is compiled as a dynamic library via the This is only useful if the program is compiled as a dynamic library via the
``--app:lib`` command-line option. `--app:lib`:option: command-line option.
Threads Threads
======= =======
To enable thread support the ``--threads:on`` command-line switch needs to To enable thread support the `--threads:on`:option: command-line switch needs to
be used. The system_ module then contains several threading primitives. be used. The system_ module then contains several threading primitives.
See the `threads <threads.html>`_ and `channels <channels.html>`_ modules See the `threads <threads.html>`_ and `channels <channels.html>`_ modules
for the low-level thread API. There are also high-level parallelism constructs for the low-level thread API. There are also high-level parallelism constructs
@ -7864,7 +7865,7 @@ any of its parameters contain a `ref` or `closure` type. This enforces
the *no heap sharing restriction*. the *no heap sharing restriction*.
Routines that are imported from C are always assumed to be `gcsafe`. Routines that are imported from C are always assumed to be `gcsafe`.
To disable the GC-safety checking the ``--threadAnalysis:off`` command-line To disable the GC-safety checking the `--threadAnalysis:off`:option: command-line
switch can be used. This is a temporary workaround to ease the porting effort switch can be used. This is a temporary workaround to ease the porting effort
from old code to the new threading model. from old code to the new threading model.

240
doc/nimc.rst
View file

@ -1,5 +1,3 @@
.. default-role:: code
=================================== ===================================
Nim Compiler User Guide Nim Compiler User Guide
=================================== ===================================
@ -7,8 +5,12 @@
:Author: Andreas Rumpf :Author: Andreas Rumpf
:Version: |nimversion| :Version: |nimversion|
.. default-role:: code
.. include:: rstcommon.rst
.. contents:: .. contents::
..
"Look at you, hacker. A pathetic creature of meat and bone, panting and "Look at you, hacker. A pathetic creature of meat and bone, panting and
sweating as you run through my corridors. How can you challenge a perfect, sweating as you run through my corridors. How can you challenge a perfect,
immortal machine?" immortal machine?"
@ -32,6 +34,9 @@ Command-line switches
--------------------- ---------------------
Basic command-line switches are: Basic command-line switches are:
.. no syntax highlighting in the below included files at the moment
.. default-role:: code
Usage: Usage:
.. include:: basicopt.txt .. include:: basicopt.txt
@ -43,11 +48,12 @@ Advanced command-line switches are:
.. include:: advopt.txt .. include:: advopt.txt
.. include:: rstcommon.rst
List of warnings List of warnings
---------------- ----------------
Each warning can be activated individually with `--warning[NAME]:on|off` or Each warning can be activated individually with `--warning[NAME]:on|off`:option: or
in a `push` pragma. in a `push` pragma.
========================== ============================================ ========================== ============================================
@ -71,7 +77,7 @@ User Some user-defined warning.
List of hints List of hints
------------- -------------
Each hint can be activated individually with `--hint[NAME]:on|off` or in a Each hint can be activated individually with `--hint[NAME]:on|off`:option: or in a
`push` pragma. `push` pragma.
========================== ============================================ ========================== ============================================
@ -132,22 +138,22 @@ Level Description
Compile-time symbols Compile-time symbols
-------------------- --------------------
Through the `-d:x` or `--define:x` switch you can define compile-time Through the `-d:x`:option: or `--define:x`:option: switch you can define compile-time
symbols for conditional compilation. The defined switches can be checked in symbols for conditional compilation. The defined switches can be checked in
source code with the `when statement source code with the `when statement
<manual.html#statements-and-expressions-when-statement>`_ and <manual.html#statements-and-expressions-when-statement>`_ and
`defined proc <system.html#defined,untyped>`_. The typical use of this switch is `defined proc <system.html#defined,untyped>`_. The typical use of this switch is
to enable builds in release mode (`-d:release`) where optimizations are to enable builds in release mode (`-d:release`:option:) where optimizations are
enabled for better performance. Another common use is the `-d:ssl` switch to enabled for better performance. Another common use is the `-d:ssl`:option: switch to
activate SSL sockets. activate SSL sockets.
Additionally, you may pass a value along with the symbol: `-d:x=y` Additionally, you may pass a value along with the symbol: `-d:x=y`:option:
which may be used in conjunction with the `compile-time define which may be used in conjunction with the `compile-time define
pragmas<manual.html#implementation-specific-pragmas-compileminustime-define-pragmas>`_ pragmas<manual.html#implementation-specific-pragmas-compileminustime-define-pragmas>`_
to override symbols during build time. to override symbols during build time.
Compile-time symbols are completely **case insensitive** and underscores are Compile-time symbols are completely **case insensitive** and underscores are
ignored too. `--define:FOO` and `--define:foo` are identical. ignored too. `--define:FOO`:option: and `--define:foo`:option: are identical.
Compile-time symbols starting with the `nim` prefix are reserved for the Compile-time symbols starting with the `nim` prefix are reserved for the
implementation and should not be used elsewhere. implementation and should not be used elsewhere.
@ -156,28 +162,47 @@ implementation and should not be used elsewhere.
Configuration files Configuration files
------------------- -------------------
**Note:** The *project file name* is the name of the `.nim` file that is **Note:** The *project file name* is the name of the ``.nim`` file that is
passed as a command-line argument to the compiler. passed as a command-line argument to the compiler.
The `nim` executable processes configuration files in the following The `nim`:cmd: executable processes configuration files in the following
directories (in this order; later files overwrite previous settings): directories (in this order; later files overwrite previous settings):
1) `$nim/config/nim.cfg`, `/etc/nim/nim.cfg` (UNIX) or ``<Nim's installation directory>\config\nim.cfg`` (Windows). This file can be skipped with the `--skipCfg` command line option. 1) ``$nim/config/nim.cfg``, ``/etc/nim/nim.cfg`` (UNIX) or
2) If environment variable `XDG_CONFIG_HOME` is defined, `$XDG_CONFIG_HOME/nim/nim.cfg` or `~/.config/nim/nim.cfg` (POSIX) or `%APPDATA%/nim/nim.cfg` (Windows). This file can be skipped with the `--skipUserCfg` command line option. ``<Nim's installation directory>\config\nim.cfg`` (Windows).
3) `$parentDir/nim.cfg` where `$parentDir` stands for any parent directory of the project file's path. These files can be skipped with the `--skipParentCfg` command-line option. This file can be skipped with the `--skipCfg`:option: command line option.
4) `$projectDir/nim.cfg` where `$projectDir` stands for the project file's path. This file can be skipped with the `--skipProjCfg` command-line option. 2) If environment variable `XDG_CONFIG_HOME` is defined,
5) A project can also have a project-specific configuration file named `$project.nim.cfg` that resides in the same directory as `$project.nim`. This file can be skipped with the `--skipProjCfg` command-line option. ``$XDG_CONFIG_HOME/nim/nim.cfg`` or ``~/.config/nim/nim.cfg`` (POSIX) or
``%APPDATA%/nim/nim.cfg`` (Windows).
This file can be skipped with the `--skipUserCfg`:option: command line
option.
3) ``$parentDir/nim.cfg`` where ``$parentDir`` stands for any parent
directory of the project file's path.
These files can be skipped with the `--skipParentCfg`:option:
command-line option.
4) ``$projectDir/nim.cfg`` where ``$projectDir`` stands for the project
file's path.
This file can be skipped with the `--skipProjCfg`:option:
command-line option.
5) A project can also have a project-specific configuration file named
``$project.nim.cfg`` that resides in the same directory as ``$project.nim``.
This file can be skipped with the `--skipProjCfg`:option:
command-line option.
Command-line settings have priority over configuration file settings. Command-line settings have priority over configuration file settings.
The default build of a project is a `debug build`:idx:. To compile a The default build of a project is a `debug build`:idx:. To compile a
`release build`:idx: define the `release` symbol:: `release build`:idx: define the `release` symbol:
.. code:: cmd
nim c -d:release myproject.nim nim c -d:release myproject.nim
To compile a `dangerous release build`:idx: define the `danger` symbol:: To compile a `dangerous release build`:idx: define the `danger` symbol:
.. code:: cmd
nim c -d:danger myproject.nim nim c -d:danger myproject.nim
@ -189,10 +214,10 @@ Nim has the concept of a global search path (PATH) that is queried to
determine where to find imported modules or include files. If multiple files are determine where to find imported modules or include files. If multiple files are
found an ambiguity error is produced. found an ambiguity error is produced.
`nim dump` shows the contents of the PATH. `nim dump`:cmd: shows the contents of the PATH.
However before the PATH is used the current directory is checked for the However before the PATH is used the current directory is checked for the
file's existence. So if PATH contains `$lib` and `$lib/bar` and the file's existence. So if PATH contains ``$lib`` and ``$lib/bar`` and the
directory structure looks like this:: directory structure looks like this::
$lib/x.nim $lib/x.nim
@ -202,26 +227,26 @@ directory structure looks like this::
other.nim other.nim
And `main` imports `x`, `foo/x` is imported. If `other` imports `x` And `main` imports `x`, `foo/x` is imported. If `other` imports `x`
then both `$lib/x.nim` and `$lib/bar/x.nim` match but `$lib/x.nim` is used then both ``$lib/x.nim`` and ``$lib/bar/x.nim`` match but ``$lib/x.nim`` is used
as it is the first match. as it is the first match.
Generated C code directory Generated C code directory
-------------------------- --------------------------
The generated files that Nim produces all go into a subdirectory called The generated files that Nim produces all go into a subdirectory called
`nimcache`. Its full path is ``nimcache``. Its full path is
- `$XDG_CACHE_HOME/nim/$projectname(_r|_d)` or `~/.cache/nim/$projectname(_r|_d)` - ``$XDG_CACHE_HOME/nim/$projectname(_r|_d)`` or ``~/.cache/nim/$projectname(_r|_d)``
on Posix on Posix
- `$HOME/nimcache/$projectname(_r|_d)` on Windows. - ``$HOME\nimcache\$projectname(_r|_d)`` on Windows.
The `_r` suffix is used for release builds, `_d` is for debug builds. The `_r` suffix is used for release builds, `_d` is for debug builds.
This makes it easy to delete all generated files. This makes it easy to delete all generated files.
The `--nimcache` The `--nimcache`:option:
`compiler switch <#compiler-usage-commandminusline-switches>`_ can be used to `compiler switch <#compiler-usage-commandminusline-switches>`_ can be used to
to change the `nimcache` directory. to change the ``nimcache`` directory.
However, the generated C code is not platform-independent. C code generated for However, the generated C code is not platform-independent. C code generated for
Linux does not compile on Windows, for instance. The comment on top of the Linux does not compile on Windows, for instance. The comment on top of the
@ -231,34 +256,40 @@ C file lists the OS, CPU, and CC the file has been compiled for.
Compiler Selection Compiler Selection
================== ==================
To change the compiler from the default compiler (at the command line):: To change the compiler from the default compiler (at the command line):
.. code:: cmd
nim c --cc:llvm_gcc --compile_only myfile.nim nim c --cc:llvm_gcc --compile_only myfile.nim
This uses the configuration defined in ``config\nim.cfg`` for `lvm_gcc`. This uses the configuration defined in ``config\nim.cfg`` for `llvm_gcc`:cmd:.
If nimcache already contains compiled code from a different compiler for the same project, If nimcache already contains compiled code from a different compiler for the same project,
add the `-f` flag to force all files to be recompiled. add the `-f`:option: flag to force all files to be recompiled.
The default compiler is defined at the top of ``config\nim.cfg``. The default compiler is defined at the top of ``config\nim.cfg``.
Changing this setting affects the compiler used by `koch` to (re)build Nim. Changing this setting affects the compiler used by `koch`:cmd: to (re)build Nim.
To use the `CC` environment variable, use `nim c --cc:env myfile.nim`. To use the To use the `CC` environment variable, use `nim c --cc:env myfile.nim`:cmd:.
`CXX` environment variable, use `nim cpp --cc:env myfile.nim`. `--cc:env` is available To use the `CXX` environment variable, use `nim cpp --cc:env myfile.nim`:cmd:.
since Nim version 1.4. `--cc:env`:option: is available since Nim version 1.4.
Cross-compilation Cross-compilation
================= =================
To cross compile, use for example:: To cross compile, use for example:
.. code:: cmd
nim c --cpu:i386 --os:linux --compileOnly --genScript myproject.nim nim c --cpu:i386 --os:linux --compileOnly --genScript myproject.nim
Then move the C code and the compile script `compile_myproject.sh` to your Then move the C code and the compile script `compile_myproject.sh`:cmd: to your
Linux i386 machine and run the script. Linux i386 machine and run the script.
Another way is to make Nim invoke a cross compiler toolchain:: Another way is to make Nim invoke a cross compiler toolchain:
.. code:: cmd
nim c --cpu:arm --os:linux myproject.nim nim c --cpu:arm --os:linux myproject.nim
@ -274,17 +305,22 @@ configuration file should contain something like::
Cross-compilation for Windows Cross-compilation for Windows
============================= =============================
To cross-compile for Windows from Linux or macOS using the MinGW-w64 toolchain:: To cross-compile for Windows from Linux or macOS using the MinGW-w64 toolchain:
.. code:: cmd
nim c -d:mingw myproject.nim nim c -d:mingw myproject.nim
Use `--cpu:i386` or `--cpu:amd64` to switch the CPU architecture. Use `--cpu:i386`:option: or `--cpu:amd64`:option: to switch the CPU architecture.
The MinGW-w64 toolchain can be installed as follows:: The MinGW-w64 toolchain can be installed as follows:
Ubuntu: apt install mingw-w64 .. code:: cmd
CentOS: yum install mingw32-gcc | mingw64-gcc - requires EPEL
OSX: brew install mingw-w64 apt install mingw-w64 # Ubuntu
yum install mingw32-gcc
yum install mingw64-gcc # CentOS - requires EPEL
brew install mingw-w64 # OSX
Cross-compilation for Android Cross-compilation for Android
@ -298,7 +334,7 @@ The first one is to treat Android as a simple Linux and use
directly on android as if it was Linux. These programs are console-only directly on android as if it was Linux. These programs are console-only
programs that can't be distributed in the Play Store. programs that can't be distributed in the Play Store.
Use regular `nim c` inside termux to make Android terminal programs. Use regular `nim c`:cmd: inside termux to make Android terminal programs.
Normal Android apps are written in Java, to use Nim inside an Android app Normal Android apps are written in Java, to use Nim inside an Android app
you need a small Java stub that calls out to a native library written in you need a small Java stub that calls out to a native library written in
@ -306,16 +342,16 @@ Nim using the `NDK <https://developer.android.com/ndk>`_. You can also use
`native-activity <https://developer.android.com/ndk/samples/sample_na>`_ `native-activity <https://developer.android.com/ndk/samples/sample_na>`_
to have the Java stub be auto-generated for you. to have the Java stub be auto-generated for you.
Use `nim c -c --cpu:arm --os:android -d:androidNDK --noMain:on` to Use `nim c -c --cpu:arm --os:android -d:androidNDK --noMain:on`:cmd: to
generate the C source files you need to include in your Android Studio generate the C source files you need to include in your Android Studio
project. Add the generated C files to CMake build script in your Android project. Add the generated C files to CMake build script in your Android
project. Then do the final compile with Android Studio which uses Gradle project. Then do the final compile with Android Studio which uses Gradle
to call CMake to compile the project. to call CMake to compile the project.
Because Nim is part of a library it can't have its own c style `main()` Because Nim is part of a library it can't have its own C-style `main()`:c:
so you would need to define your own `android_main` and init the Java so you would need to define your own `android_main`:c: and init the Java
environment, or use a library like SDL2 or GLFM to do it. After the Android environment, or use a library like SDL2 or GLFM to do it. After the Android
stuff is done, it's very important to call `NimMain()` in order to stuff is done, it's very important to call `NimMain()`:c: in order to
initialize Nim's garbage collector and to run the top level statements initialize Nim's garbage collector and to run the top level statements
of your program. of your program.
@ -334,14 +370,14 @@ Normal languages for iOS development are Swift and Objective C. Both of these
use LLVM and can be compiled into object files linked together with C, C++ use LLVM and can be compiled into object files linked together with C, C++
or Objective C code produced by Nim. or Objective C code produced by Nim.
Use `nim c -c --os:ios --noMain:on` to generate C files and include them in Use `nim c -c --os:ios --noMain:on`:cmd: to generate C files and include them in
your XCode project. Then you can use XCode to compile, link, package and your XCode project. Then you can use XCode to compile, link, package and
sign everything. sign everything.
Because Nim is part of a library it can't have its own c style `main()` so you Because Nim is part of a library it can't have its own C-style `main()`:c: so you
would need to define `main` that calls `autoreleasepool` and would need to define `main` that calls `autoreleasepool` and
`UIApplicationMain` to do it, or use a library like SDL2 or GLFM. After `UIApplicationMain` to do it, or use a library like SDL2 or GLFM. After
the iOS setup is done, it's very important to call `NimMain()` to the iOS setup is done, it's very important to call `NimMain()`:c: to
initialize Nim's garbage collector and to run the top-level statements initialize Nim's garbage collector and to run the top-level statements
of your program. of your program.
@ -358,17 +394,16 @@ so you need to clean those files manually to do a clean build.
Cross-compilation for Nintendo Switch Cross-compilation for Nintendo Switch
===================================== =====================================
Simply add --os:nintendoswitch Simply add `--os:nintendoswitch`:option:
to your usual `nim c` or `nim cpp` command and set the `passC` to your usual `nim c`:cmd: or `nim cpp`:cmd: command and set the `passC`:option:
and `passL` command line switches to something like: and `passL`:option: command line switches to something like:
.. code-block:: console .. code-block:: cmd
nim c ... --passC="-I$DEVKITPRO/libnx/include" ... nim c ... --passC="-I$DEVKITPRO/libnx/include" ...
--passL="-specs=$DEVKITPRO/libnx/switch.specs -L$DEVKITPRO/libnx/lib -lnx" --passL="-specs=$DEVKITPRO/libnx/switch.specs -L$DEVKITPRO/libnx/lib -lnx"
or setup a nim.cfg file like so: or setup a ``nim.cfg`` file like so::
.. code-block:: Nim
#nim.cfg #nim.cfg
--passC="-I$DEVKITPRO/libnx/include" --passC="-I$DEVKITPRO/libnx/include"
--passL="-specs=$DEVKITPRO/libnx/switch.specs -L$DEVKITPRO/libnx/lib -lnx" --passL="-specs=$DEVKITPRO/libnx/switch.specs -L$DEVKITPRO/libnx/lib -lnx"
@ -377,12 +412,14 @@ The DevkitPro setup must be the same as the default with their new installer
`here for Mac/Linux <https://github.com/devkitPro/pacman/releases>`_ or `here for Mac/Linux <https://github.com/devkitPro/pacman/releases>`_ or
`here for Windows <https://github.com/devkitPro/installer/releases>`_. `here for Windows <https://github.com/devkitPro/installer/releases>`_.
For example, with the above-mentioned config:: For example, with the above-mentioned config:
.. code:: cmd
nim c --os:nintendoswitch switchhomebrew.nim nim c --os:nintendoswitch switchhomebrew.nim
This will generate a file called `switchhomebrew.elf` which can then be turned into This will generate a file called ``switchhomebrew.elf`` which can then be turned into
an nro file with the `elf2nro` tool in the DevkitPro release. Examples can be found at an nro file with the `elf2nro`:cmd: tool in the DevkitPro release. Examples can be found at
`the nim-libnx github repo <https://github.com/jyapayne/nim-libnx.git>`_. `the nim-libnx github repo <https://github.com/jyapayne/nim-libnx.git>`_.
There are a few things that don't work because the DevkitPro libraries don't support them. There are a few things that don't work because the DevkitPro libraries don't support them.
@ -402,16 +439,20 @@ DLL generation
Nim supports the generation of DLLs. However, there must be only one Nim supports the generation of DLLs. However, there must be only one
instance of the GC per process/address space. This instance is contained in instance of the GC per process/address space. This instance is contained in
`nimrtl.dll`. This means that every generated Nim DLL depends ``nimrtl.dll``. This means that every generated Nim DLL depends
on `nimrtl.dll`. To generate the "nimrtl.dll" file, use the command:: on ``nimrtl.dll``. To generate the "nimrtl.dll" file, use the command:
.. code:: cmd
nim c -d:release lib/nimrtl.nim nim c -d:release lib/nimrtl.nim
To link against `nimrtl.dll` use the command:: To link against ``nimrtl.dll`` use the command:
.. code:: cmd
nim c -d:useNimRtl myprog.nim nim c -d:useNimRtl myprog.nim
**Note**: Currently the creation of `nimrtl.dll` with thread support has **Note**: Currently the creation of ``nimrtl.dll`` with thread support has
never been tested and is unlikely to work! never been tested and is unlikely to work!
@ -427,20 +468,20 @@ Define Effect
====================== ========================================================= ====================== =========================================================
`release` Turns on the optimizer. `release` Turns on the optimizer.
More aggressive optimizations are possible, e.g.: More aggressive optimizations are possible, e.g.:
`--passC:-ffast-math` (but see issue #10305) `--passC:-ffast-math`:option: (but see issue #10305)
`danger` Turns off all runtime checks and turns on the optimizer. `danger` Turns off all runtime checks and turns on the optimizer.
`useFork` Makes `osproc` use `fork` instead of `posix_spawn`. `useFork` Makes `osproc` use `fork`:c: instead of `posix_spawn`:c:.
`useNimRtl` Compile and link against `nimrtl.dll`. `useNimRtl` Compile and link against ``nimrtl.dll``.
`useMalloc` Makes Nim use C's `malloc`:idx: instead of Nim's `useMalloc` Makes Nim use C's `malloc`:idx: instead of Nim's
own memory manager, albeit prefixing each allocation with own memory manager, albeit prefixing each allocation with
its size to support clearing memory on reallocation. its size to support clearing memory on reallocation.
This only works with `gc:none`, `gc:arc` and This only works with `--gc:none`:option:,
`--gc:orc`. `--gc:arc`:option: and `--gc:orc`:option:.
`useRealtimeGC` Enables support of Nim's GC for *soft* realtime `useRealtimeGC` Enables support of Nim's GC for *soft* realtime
systems. See the documentation of the `gc <gc.html>`_ systems. See the documentation of the `gc <gc.html>`_
for further information. for further information.
`logGC` Enable GC logging to stdout. `logGC` Enable GC logging to stdout.
`nodejs` The JS target is actually `node.js`. `nodejs` The JS target is actually ``node.js``.
`ssl` Enables OpenSSL support for the sockets module. `ssl` Enables OpenSSL support for the sockets module.
`memProfiler` Enables memory profiling for the native GC. `memProfiler` Enables memory profiling for the native GC.
`uClibc` Use uClibc instead of libc. (Relevant for Unix-like OSes) `uClibc` Use uClibc instead of libc. (Relevant for Unix-like OSes)
@ -448,16 +489,16 @@ Define Effect
what's in the Nim file with what's in the C header. what's in the Nim file with what's in the C header.
This may become enabled by default in the future. This may become enabled by default in the future.
`tempDir` This symbol takes a string as its value, like `tempDir` This symbol takes a string as its value, like
`--define:tempDir:/some/temp/path` to override the `--define:tempDir:/some/temp/path`:option: to override
temporary directory returned by `os.getTempDir()`. the temporary directory returned by `os.getTempDir()`.
The value **should** end with a directory separator The value **should** end with a directory separator
character. (Relevant for the Android platform) character. (Relevant for the Android platform)
`useShPath` This symbol takes a string as its value, like `useShPath` This symbol takes a string as its value, like
`--define:useShPath:/opt/sh/bin/sh` to override the `--define:useShPath:/opt/sh/bin/sh`:option: to override
path for the `sh` binary, in cases where it is not the path for the `sh`:cmd: binary, in cases where it is
located in the default location `/bin/sh`. not located in the default location ``/bin/sh``.
`noSignalHandler` Disable the crash handler from `system.nim`. `noSignalHandler` Disable the crash handler from ``system.nim``.
`globalSymbols` Load all `{.dynlib.}` libraries with the `RTLD_GLOBAL` `globalSymbols` Load all `{.dynlib.}` libraries with the `RTLD_GLOBAL`:c:
flag on Posix systems to resolve symbols in subsequently flag on Posix systems to resolve symbols in subsequently
loaded libraries. loaded libraries.
====================== ========================================================= ====================== =========================================================
@ -474,20 +515,21 @@ generator and are subject to change.
LineDir option LineDir option
-------------- --------------
The `lineDir` option can be turned on or off. If turned on the The `--lineDir`:option: option can be turned on or off. If turned on the
generated C code contains `#line` directives. This may be helpful for generated C code contains `#line`:c: directives. This may be helpful for
debugging with GDB. debugging with GDB.
StackTrace option StackTrace option
----------------- -----------------
If the `stackTrace` option is turned on, the generated C contains code to If the `--stackTrace`:option: option is turned on, the generated C contains code to
ensure that proper stack traces are given if the program crashes or some uncaught exception is raised. ensure that proper stack traces are given if the program crashes or some uncaught exception is raised.
LineTrace option LineTrace option
---------------- ----------------
The `lineTrace` option implies the `stackTrace` option. If turned on, The `--lineTrace`:option: option implies the `stackTrace`:option: option.
If turned on,
the generated C contains code to ensure that proper stack traces with line the generated C contains code to ensure that proper stack traces with line
number information are given if the program crashes or an uncaught exception number information are given if the program crashes or an uncaught exception
is raised. is raised.
@ -497,11 +539,13 @@ DynlibOverride
============== ==============
By default Nim's `dynlib` pragma causes the compiler to generate By default Nim's `dynlib` pragma causes the compiler to generate
`GetProcAddress` (or their Unix counterparts) `GetProcAddress`:cpp: (or their Unix counterparts)
calls to bind to a DLL. With the `dynlibOverride` command line switch this calls to bind to a DLL. With the `dynlibOverride`:option: command line switch this
can be prevented and then via `--passL` the static library can be linked can be prevented and then via `--passL`:option: the static library can be linked
against. For instance, to link statically against Lua this command might work against. For instance, to link statically against Lua this command might work
on Linux:: on Linux:
.. code:: cmd
nim c --dynlibOverride:lua --passL:liblua.lib program.nim nim c --dynlibOverride:lua --passL:liblua.lib program.nim
@ -509,8 +553,8 @@ on Linux::
Backend language options Backend language options
======================== ========================
The typical compiler usage involves using the `compile` or `c` command to The typical compiler usage involves using the `compile`:option: or `c`:option:
transform a `.nim` file into one or more `.c` files which are then command to transform a ``.nim`` file into one or more ``.c`` files which are then
compiled with the platform's C compiler into a static binary. However, there compiled with the platform's C compiler into a static binary. However, there
are other commands to compile to C++, Objective-C, or JavaScript. More details are other commands to compile to C++, Objective-C, or JavaScript. More details
can be read in the `Nim Backend Integration document <backends.html>`_. can be read in the `Nim Backend Integration document <backends.html>`_.
@ -520,7 +564,7 @@ Nim documentation tools
======================= =======================
Nim provides the `doc`:idx: command to generate HTML Nim provides the `doc`:idx: command to generate HTML
documentation from `.nim` source files. Only exported symbols will appear in documentation from ``.nim`` source files. Only exported symbols will appear in
the output. For more details `see the docgen documentation <docgen.html>`_. the output. For more details `see the docgen documentation <docgen.html>`_.
Nim idetools integration Nim idetools integration
@ -558,19 +602,21 @@ embedded microprocessors with only a few kilobytes of memory.
A good start is to use the `any` operating target together with the A good start is to use the `any` operating target together with the
`malloc` memory allocator and the `arc` garbage collector. For example: `malloc` memory allocator and the `arc` garbage collector. For example:
`nim c --os:any --gc:arc -d:useMalloc [...] x.nim` .. code:: cmd
- `--gc:arc` will enable the reference counting memory management instead nim c --os:any --gc:arc -d:useMalloc [...] x.nim
- `--gc:arc`:option: will enable the reference counting memory management instead
of the default garbage collector. This enables Nim to use heap memory which of the default garbage collector. This enables Nim to use heap memory which
is required for strings and seqs, for example. is required for strings and seqs, for example.
- The `--os:any` target makes sure Nim does not depend on any specific - The `--os:any`:option: target makes sure Nim does not depend on any specific
operating system primitives. Your platform should support only some basic operating system primitives. Your platform should support only some basic
ANSI C library `stdlib` and `stdio` functions which should be available ANSI C library `stdlib` and `stdio` functions which should be available
on almost any platform. on almost any platform.
- The `-d:useMalloc` option configures Nim to use only the standard C memory - The `-d:useMalloc`:option: option configures Nim to use only the standard C memory
manage primitives `malloc()`, `free()`, `realloc()`. manage primitives `malloc()`:c:, `free()`:c:, `realloc()`:c:.
If your platform does not provide these functions it should be trivial to If your platform does not provide these functions it should be trivial to
provide an implementation for them and link these to your program. provide an implementation for them and link these to your program.
@ -580,13 +626,13 @@ additional flags to both the Nim compiler and the C compiler and/or linker
to optimize the build for size. For example, the following flags can be used to optimize the build for size. For example, the following flags can be used
when targeting a gcc compiler: when targeting a gcc compiler:
`--opt:size --passC:-flto --passL:-flto` `--opt:size --passC:-flto --passL:-flto`:option:
The `--opt:size` flag instructs Nim to optimize code generation for small The `--opt:size`:option: flag instructs Nim to optimize code generation for small
size (with the help of the C compiler), the `flto` flags enable link-time size (with the help of the C compiler), the `-flto`:option: flags enable link-time
optimization in the compiler and linker. optimization in the compiler and linker.
Check the `Cross-compilation` section for instructions on how to compile the Check the `Cross-compilation`_ section for instructions on how to compile the
program for your target. program for your target.
Nim for realtime systems Nim for realtime systems
@ -603,7 +649,7 @@ The Nim programming language has no concept of Posix's signal handling
mechanisms. However, the standard library offers some rudimentary support mechanisms. However, the standard library offers some rudimentary support
for signal handling, in particular, segmentation faults are turned into for signal handling, in particular, segmentation faults are turned into
fatal errors that produce a stack trace. This can be disabled with the fatal errors that produce a stack trace. This can be disabled with the
`-d:noSignalHandler` switch. `-d:noSignalHandler`:option: switch.
Optimizing for Nim Optimizing for Nim

45
doc/rstcommon.rst
View file

@ -1,6 +1,51 @@
..
Usage of this file:
Add this in the beginning of *.rst file::
.. default-role:: code
.. include:: rstcommon.rst
It's the current trick for brevity and compatibility with both Github and
rst2html.py, considering that Github cannot highlight Nim in
RST files anyway and it does not include files.
This way interpreted text is displayed with monospaced font in Github
and it's displayed an Nim code in both rst2html.py
(note ".. default-role:: Nim" above) and `nim rst2html`.
For files that are user manual and consist of stuff like cmdline
option description, use 'code' as a **real** default role:
.. include:: rstcommon.rst
.. default-role:: code
.. define language roles explicitly (for compatibility with rst2html.py):
.. role:: nim(code) .. role:: nim(code)
:language: nim :language: nim
.. default-role:: nim .. default-role:: nim
.. role:: c(code)
:language: c
.. role:: cpp(code)
:language: cpp
.. role:: yaml(code)
:language: yaml
.. role:: python(code)
:language: python
.. role:: java(code)
:language: java
.. role:: csharp(code)
:language: csharp
.. role:: cmd(code)
.. role:: program(code)
.. role:: option(code)