Merge pull request #4445 from Jeff-Ciesielski/jeffc/define_assignments

Add the ability to pass a value with the -d flag

doc/basicopt.txt

@@ -11,7 +11,9 @@ Arguments:
   arguments are passed to the program being run (if --run option is selected)
 Options:
   -p, --path:PATH           add path to search paths
-  -d, --define:SYMBOL       define a conditional symbol
+  -d, --define:SYMBOL(:VAL)
+                            define a conditional symbol
+                            (Optionally: Define the value for that symbol)
   -u, --undef:SYMBOL        undefine a conditional symbol
   -f, --forceBuild          force rebuilding of all modules
   --stackTrace:on|off       turn stack tracing on|off

doc/manual/pragmas.txt

@@ -1011,3 +1011,30 @@ debugging:
 
   # ... complex code here that produces crashes ...
 
+compile time define pragmas
+---------------------------
+
+The pragmas listed here can be used to optionally accept values from
+the -d/--define option at compile time.
+
+The implementation currently provides the following possible options (various
+others may be added later).
+
+===============  ============================================
+pragma           description
+===============  ============================================
+intdefine        Reads in a build-time define as an integer
+strdefine        Reads in a build-time define as a string
+===============  ============================================
+
+.. code-block:: nim
+   const FooBar {.intdefine.}: int = 5
+   echo FooBar
+
+.. code-block:: bash
+   nim c -d:FooBar=42 foobar.c
+
+In the above example, providing the -d flag causes the symbol
+``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
+used.

doc/nimc.rst

@@ -98,6 +98,11 @@ 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>`_.
 
+Additionally, you may pass a value along with the symbol: ``-d:x=y``
+which may be used in conjunction with the `compile time define
+pragmas<manual.html#implementation-specific-pragmas-compile-time-define-pragmas>`_
+to override symbols during build time.
+
 
 Configuration files
 -------------------
@@ -370,7 +375,10 @@ For example, to generate code for an `AVR`:idx: processor use this command::
 For the ``standalone`` target one needs to provide
 a file ``panicoverride.nim``.
 See ``tests/manyloc/standalone/panicoverride.nim`` for an example
-implementation.
+implementation.  Additionally, users should specify the
+amount of heap space to use with the ``-d:StandaloneHeapSize=<size>``
+command line switch.  Note that the total heap size will be
+``<size> * sizeof(float64)``.
 
 
 Nim for realtime systems