diff options
| -rw-r--r-- | doc/nimrodc.txt | 12 | ||||
| -rw-r--r-- | lib/system.nim | 20 |
2 files changed, 29 insertions, 3 deletions
diff --git a/doc/nimrodc.txt b/doc/nimrodc.txt index e4f1c41dc..fea1037da 100644 --- a/doc/nimrodc.txt +++ b/doc/nimrodc.txt @@ -87,6 +87,18 @@ Level Description for compiler developers. ===== ============================================ + +Compile time symbols +-------------------- + +Through the ``-d:x`` or ``--define:x`` switch you can define compile time +symbols for conditional compilation. The defined switches can be checked in +source code with the `when statement <manual.html#when-statement>`_ and +`defined proc <system.html#defined>`_. The typical use of this switch is to +enable builds in release mode (``-d:release``) where certain safety checks are +omitted for better performance. Another common use is the ``-d:ssl`` switch to +activate `SSL sockets <sockets.html>`_. + Configuration files ------------------- diff --git a/lib/system.nim b/lib/system.nim index 4a4872b98..2f24f68b1 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -88,6 +88,15 @@ proc defined*(x: expr): bool {.magic: "Defined", noSideEffect.} ## when not defined(strutils.toUpper): ## # provide our own toUpper proc here, because strutils is ## # missing it. + ## + ## You can also check external symbols introduced through the compiler's + ## `-d:x switch <nimrodc.html#compile-time-symbols>`_ to enable build time + ## conditionals: + ## + ## .. code-block:: Nimrod + ## when not defined(release): + ## # Do here programmer friendly expensive sanity checks. + ## # Put here the normal code when defined(useNimRtl): {.deadCodeElim: on.} @@ -2812,10 +2821,15 @@ when true: THide(raiseAssert)(msg) template assert*(cond: bool, msg = "") = - ## provides a means to implement `programming by contracts`:idx: in Nimrod. + ## Raises ``EAssertionFailure`` with `msg` if `cond` is false. + ## + ## Provides a means to implement `programming by contracts`:idx: in Nimrod. ## ``assert`` evaluates expression ``cond`` and if ``cond`` is false, it - ## raises an ``EAssertionFailure`` exception. However, the compiler may - ## not generate any code at all for ``assert`` if it is advised to do so. + ## raises an ``EAssertionFailure`` exception. However, the compiler may not + ## generate any code at all for ``assert`` if it is advised to do so through + ## the ``-d:release`` or ``--assertions:off`` `command line switches + ## <nimrodc.html#command-line-switches>`_. + ## ## Use ``assert`` for debugging purposes only. bind instantiationInfo mixin failedAssertImpl |