SIP78 Convert switches to run time options part 3 (#114)

Author: Alomir

docs/CHANGELOG.md

@@ -31,12 +31,14 @@ sections to include in release notes:
 - Build docs and push to gh-pages (#41)
 - events.out file for agronomic event handling (#57)
 - Utility `tools/trim_first_chars.sh` to trim the first n characters from every row in a file, useful for updating old input files to remove location column
-- Expanded smoke test cases to better cover SIPNET modeling options (#109)
+- Expanded smoke test cases to better cover SIPNET modeling options (#109, #114)
+- Converted all compile-time switches not removed or hard-coded to be on into switches to run-time options (#114)
 
 ### Fixed
 
 - Fixed OOM issue when reading bad data (#38, #45)
 - Event order checks no longer only compare to first record (#74, #77)
+- Fixed long-standing bug wherein microbePulseEff was not set to 0 when MICROBES was off (#114)
 
 ### Changed
 
@@ -52,6 +54,7 @@ sections to include in release notes:
 - Removed obsolete run types senstest and montecarlo and associated code (#69, #76)
 - Removed obsolete estimate program and associated code (#70, #82)
 - Removed multi-site support; in particular, output files no longer have a location column (#92)
+- Removed or hard-codes 'on' many compile time switches (#114)
 
 ### Git SHA
 [TBD]

docs/developer-guide/cli-options.md

@@ -11,7 +11,7 @@ When adding a new command-line option, you will need to add a corresponding memb
 
 ## Important Notes
 
-**A note on naming:** 
+### Naming
 
 Each command-line option must have a corresponding entry in the `Context` struct. SIPNET uses a mapping system to 
 link the command-line option (e.g. `print_header`) to its `Context` member (in this case, `printHeader`).
@@ -21,11 +21,12 @@ The mapping is created using the `nameToKey` function in `common/context.c` that
 - removes all non-alphanumeric characters.
 - converts alpha characters to lowercase. 
 
-For the mapping to work, the option name (e.g., `print_header`) and `Context` member name (in this case, `printHeader`) must generate the same key (e.g. `print_header` and `printHeader` both generate `printheader`).
+For the mapping to work, the option name (e.g., `print_header`) and `Context` member name (in this case, 
+`printHeader`) must generate the same key (e.g. `print_header` and `printHeader` both generate `printheader`).
 
 Each key must be unique across the `Context` member names.
 
-**A note on precedence:** 
+### Precedence
 
 SIPNET options can be specified in either (or both) a config file or a command-line option. Command-line options are
 have precedence over config file options.
@@ -35,6 +36,8 @@ This means that:
 - Options must be set via the macros `CREATE_INT_CONTEXT`/`CREATE_CHAR_CONTEXT` when they are created.
 - The functions `updateIntContext`/`updateCharContext` must be used when updating a value.
 
+See the Function/Macro Reference at the end for more information.
+
 ## Steps to Add Each Type of Option
 
 For each type of option, the steps are similar:
@@ -97,6 +100,11 @@ Here are the steps to add a string-valued option:
    2. Update `parseCLIArgs()`... [details TBD]
    3. Update `usage()` to document the new option in the help text
 
+### Long-Form Only Options
+
+When adding to the `long_options` struct in step 3(i), give an int value as the last element of the the new
+struct. This is the index that should be used in the `parseCLIArgs()` switch statement for handling the new
+option. The int value must be unique among the other case labels.
 
 ## Additional Steps [TBD]
 
@@ -111,10 +119,83 @@ Here are the steps to add a string-valued option:
   - Add tests for both the new option and its negation (if applicable) in [TBD].
   - Anything to here to make sure this works in `sipnet.in` [TBD]?
 
-## Long-Form Only Options
-
-[TBD: fold this in above? This isn't that complicated; let's see if anything changes in the next round]
-
-When adding to the `long_options` struct in step 3(i), give an int value as the last element of the the new
-struct. This is the index that should be used in the `parseCLIArgs()` switch statement for handling the new 
-option. The int value must be unique among the other case labels.
+## Function/Macro Reference
+
+When adding a new CLI option, these functions and macros should be used to create and update
+the corresponding fields in the `Context` struct.
+
+### `CREATE_INT_CONTEXT`
+
+This macro is used to initialize the `Context` field as well as create the necessary 
+metadata information for integer-based arguments, both flag and not.
+This macro is used in the `initContext` function in `src/common/context.c`.
+
+Syntax:
+```c
+CREATE_INT_CONTEXT(name, printName, value, flag)
+```
+Arguments:
+- `name`: the exact name (no quotes) of the `Context` struct member used in `Context.h`
+- `printName`: the name used for this option when printing via `--dump-config`
+- `value`: the default integer value for this option; the defined values `ARG_ON` and `ARG_OFF` can be used for flag options
+- `flag`: `FLAG_YES` or `FLAG_NO` to indicate whether this is a flag option
+
+Examples:
+<br>`CREATE_INT_CONTEXT(snow, "SNOW", ARG_ON, FLAG_YES);`
+<br>`CREATE_INT_CONTEXT(numSoilCarbonPools, "NUM_SOIL_CARBON_POOLS", 3, FLAG_NO);`
+
+### `CREATE_CHAR_CONTEXT`
+
+This macro is used to initialize the `Context` field as well as create the necessary
+metadata information for string-based arguments.
+This macro is used in the `initContext` function in `src/common/context.c`.
+
+Syntax:
+```c
+CREATE_CHAR_CONTEXT(name, printName, value)
+```
+Arguments:
+- `name`: the exact name (no quotes) of the `Context` struct member used in `Context.h`
+- `printName`: the name used for this option when printing via `--dump-config`
+- `value`: the default string value for this option
+
+Examples:
+<br>`CREATE_CHAR_CONTEXT(outConfigFile, "OUT_CONFIG_FILE", NO_DEFAULT_FILE);`
+<br>`CREATE_CHAR_CONTEXT(inputFile, "INPUT_FILE", DEFAULT_INPUT_FILE);`
+
+### `updateIntContext`
+
+This function is used to update an integer-based argument, both the stored value as well as the source of that value. 
+This function is typically used in the `parseCommandLineArgs` function in `src/sipnet/cli.c`.
+Note that flag options should not need this, as they are handled automatically.
+
+Syntax:
+```c
+updateIntContext(const char *name, int value, context_source_t source)
+```
+Arguments:
+- `name`: a string that can uniquely identify the option (see [Naming](#naming) above)
+- `value`: the new integer value for the option 
+- `source`: where the value is coming from, e.g. `CTX_CONTEXT_FILE` or `CTX_COMMAND_LINE`
+
+Examples:
+<br>`updateIntContext(inputName, intVal, CTX_CONTEXT_FILE);` (from parsing the input file)
+<br>`updateIntContext("numSoilCarbonPools", intVal, CTX_COMMAND_LINE);` (from parsing the command line)
+
+### `updateCharContext`
+
+This function is used to update a string-based argument, both the stored value as well as the source of that value.
+This function is typically used in the `parseCommandLineArgs` function in `src/sipnet/cli.c`.
+
+Syntax:
+```c
+updateCharContext(const char *name, const char *value, context_source_t source)
+```
+Arguments:
+- `name`: a string that can uniquely identify the option (see [Naming](#naming) above)
+- `value`: the new string value for the option
+- `source`: where the value is coming from, e.g. `CTX_CONTEXT_FILE` or `CTX_COMMAND_LINE`
+
+Examples:
+<br>`updateCharContext(inputName, inputValue, CTX_CONTEXT_FILE);` (from parsing the input file)
+<br>`updateCharContext("inputFile", optarg, CTX_COMMAND_LINE);` (from parsing the command line)