Loading INI Files

During startup and after the internal database has been initialized as described in the section Built-in Default Configuration Settings, HPX will try to locate and load additional ini files to be used as a source for configuration properties. This allows for a wide spectrum of additional customization possibilities by the user and system administrators. The sequence of locations where HPX will try loading the ini files is well defined and documented in this section. All ini files found are merged into the internal configuration database. The merge operation itself conforms to the rules as described in the section The HPX INI File Format.

Load all component shared libraries found in the directories specified by the property hpx.component_path and retrieve their default configuration information (see section Loading Components for more details). This property can refer to a list of directories separated by ':' (Linux, Android, and MacOS) or using ';' (Windows).
Load all files named hpx.ini in the directories referenced by the property hpx.master_ini_path. This property can refer to a list of directories separated by ':' (Linux, Android, and MacOS) or using ';' (Windows).
Load a file named .hpx.ini in the current working directory, e.g. the directory the application was invoked from.
Load a file referenced by the environment variable HPX_INI. This variable is expected to provide the full path name of the ini configuration file (if any).
Load a file named /etc/hpx.ini. This lookup is done on non-Windows systems only.
Load a file named .hpx.ini in the home directory of the current user, e.g. the directory referenced by the environment variable HOME.
Load a file named .hpx.ini in the directory referenced by the environment variable PWD.
Load the file specified on the command line using the option --hpx:config.
Load all properties specified on the command line using the option --hpx:ini. The properties will be added to the database in the same sequence as they are specified on the command line. The format for those options is for instance --hpx:ini=hpx.default_stack_size=0x4000. In adddition to the explicit command line options, this will set the following properties as implied from other settings:
- hpx.parcel.address and hpx.parcel.port as set by --hpx:hpx
- hpx.agas.address, hpx.agas.port, and hpx.agas.service_mode as set by --hpx:agas
- hpx.program_name and hpx.cmd_line will be derived from the actual command line
- hpx.os_threads, and hpx.localities as set by --hpx:threads and --hpx:localities
- hpx.runtime_mode will be derived from any explicit --hpx:console, --hpx:worker, or --hpx:connect, or it will be derived from other settings, such as --hpx:node=0 which implies --hpx:console
Load files based on the pattern *.ini in all directories listed by the property hpx.ini_path. All files found during this search will be merged. The property hpx.ini_path can hold a list of directories separated by ':' (on Linux or Mac) or ';' (on Windows)
Load the file specified on the command line using the option --hpx:app-config. Note that this file will be merged as the content for a top level section [application].

	Note
	Any changes made to the configuration database caused by one of the steps will influence the loading process for all subsequent steps. For instance, if one of the ini files loaded changes the property `hpx.ini_path`, this will influence the directories searched in step 9 as described above.

Important

	Important
The HPX core library will verify that all configuration settings specified on the command line (using the `--hpx:ini` option) will be checked for validity. That means that the library will accept only known configuration settings. This is to protect the user from unintentional typos while specifying those settings. This behavior can be overwritten by appending a `'!'` to the configuration key, thus forcing the setting to be entered into the configuration database, for instance: `--hpx:ini=hpx.foo! = 1`.

The HPX core library will verify that all configuration settings specified on the command line (using the --hpx:ini option) will be checked for validity. That means that the library will accept only known configuration settings. This is to protect the user from unintentional typos while specifying those settings. This behavior can be overwritten by appending a '!' to the configuration key, thus forcing the setting to be entered into the configuration database, for instance: --hpx:ini=hpx.foo! = 1.

If any of the environment variables or files listed above is not found the corresponding loading step will be silently skipped.