general.hpp File Reference

Plans regarding configuration management. More...

Go to the source code of this file.

Detailed Description

Plans regarding configuration management.

Configuration include order
  • Configuration files such as those included in BuildSystem/Configuration/configuration_data.mak should be ordered in such a way that definitions that are likely to be useful can be used in subsequent configuration files.
  • For example, one might wish to check whether a particular machine is 32 or 64 bit and determine the paths to libraries etc based on this variable, and hence BuildSystem/Configuration/build_data.mak should appear before files such as BuildSystem/Configuration/ExternalSources/all.mak (see commit 97faa95da174bd79aec9ab3ce1ae75023d993665 ).
Configuration data overview
  • We need to get an overview on the different types of configuration data.
  • Build-related
  • External sources:
    1. See Buildsystem/ExternalSources/plans/Configuration.hpp.
  • html-pages
  • The doxygen system (see "Definitions for doxygen" below).
  • Personal information:
    1. See Buildsystem/Configuration/plans/Persons.hpp.
Configuration data format
  • Standardisation of naming configuration variables:
    1. Perhaps a directory gets the prefix "dir_", and a main directory "Directory" is then called "dir_Directory".
  • Perhaps for defining configuration variables we should always first check whether it's already defined, and if not, then look for an environment variable.
  • In order that the configuration-variables become available, the corresponding master-process has to be invoked by some makefile; so likely over time a collection of small specialised makefiles arises.
  • Splitting the definitions over several files is likely preferable from the order point of view. Shouldn't be too complicated to use them.
  • Configuration variables shall follow the rules for C-names (so no hyphens for example), since otherwise the shell can't handle them.
  • In directory .oklib a file "override.mak" is placed, where overriding definitions of configuration variables are to be put (for example variable ExternalSources could be redefined here, to use the external sources of another OKplatform-installation). DONE
  • Should the configuration-make-variables be recursive or not? Recursive variables give more power ("one never knows"), and so at the moment the decision is to make all configuration-make-variables recursive. DONE (recursive variables are needed, so that definitions can be overriden)
  • DONE (we use makefiles with makevariable-definitions for all configuration data) We could use makefile-syntax, that is, we have make-files containing only variable settings
    To be used by the C preprocessor, this has to be translated into
    #define CONFIGVAR1 value1
    #define CONFIGVAR2 value2
    This seems to work whatever value1 is (as long value1 does not contain line breaks). To be used by m4, this has to be translated into
    In both cases there might be problems if value1 for example contains a closing bracket? Perhaps we could just use the export-facility of make, so that these variables become environment variables?!? But then we would loose control.
  • The solution seems to be not to do translations, but to have all configuration-variables defined in makefiles as as make-variables. Via the export-function then we have all them plus the environment variables at hand, and every other usage of configuration variables (doxygen or an html-preprocessor) just accesses environment variables. DONE (we do as proposed here)
  • If we are going to use CMake, then perhaps the variable settings should be done in the cmake-syntax. DONE (the cmake-transition, if at all, can happen only after we have a running make-system)
Primary versus derived configurations
  • The primary configurations are under version control.
  • Derived values (like source- and link-libraries for external libraries) are to be found perhaps in system_directories/configurations ? There might be also a symbolic link to the primary configurations?
Variables for accessing external libraries (was system_definitions.mak):
  • Boost:
    • If the variable includes the "-I", then for other variables we use a suffix "_include", which we should also do for the boost-variables.
    • We need a precise and central definition of those boost-variables.
    • The default value of Boost -I/usr/local/boost-1_34_0 is stale; the recommended Boost version number is needed. DONE
      • So for every external library Extlib the default value of the Make variable Extlib should be deduced the recommended version number? DONE (yes)
    • The boost-variable definitions are inconsistent with the rest of the build-system, so they should be reverted (as discussed). DONE
  • The role of system_definitions.mak must be clarified. Do those library variables (Boost, Ubcsat) belong to it?? No: They must go the Configuration/ExternalSources --- for every external sources there one finds variables yielding access to the resources provided by it. DONE
    • system_definitions.mak should contain definitions of Make variables which are used by several makefiles. However, the prefix "system_" also implies that these variables belong to the OKlibrary and not to the external sources, so perhaps the definitions of variables relevant for the external sources are moved elsewhere. DONE
    • Perhaps all variable definitions relevant for the external sources (including version numbers) should go into ExternalSources/definitions.mak? DONE (they go for example to Configuration/ExternalSources/gcc.mak)
      1. What about that "ExternalSources/definitions_.mak" ? (This name seems strange to me anyway.) DONE (merged into ExternalSources/Makefile)
      2. The main question is about visibility. There needs to be fixed the architecture of our makefiles (w.r.t. inclusion and variable definitions). DONE (handled by the new configuration system)
  • What is the precise relation to external_sources_versions.mak ? DONE (all variables related to external sources must leave system_definitions.mak)
Definitions for doxygen
  • General make-functions are needed to overcome the restrictions on using configuration-variables in doxygen-documentation (see for example the function doxygen_html_documentation_index_location_tag in Configuration/ExternalSources/doxygen.mak).
  • It would be preferable, if the following variable definitions
    1. ALIASES
    would come from Configuration/doxygen_documentation.mak.
  • For all settings we should have specific configuration variables.
  • With every new version of doxygen, the update-wizzard of doxygen has to be run on the created doxyfile, one has to study the changes, and then one has to update the master-doxyfile accordingly. First update the created Doxyfile
    OKplatform/system_directories/aux> doxygen -u Doxyfile
    and after studying these changes, update the template
    OKlib/Buildsystem/Configuration> doxygen -u Doxyfile
  • DONE (doxygen_parameters deleted, since not needed --- parameters can also be specified on the command-line) Mention in the documentation, that via "doxygen_parameters" one can set variables from the doxygen-configuration-file (as an example present the switch to German).
  • How can we reliably refer to a specific page within the doxygen documentation? Are the url's relatively stable? DONE (yes, they are --- the temporary problem was an md5-doxygen bug)
  • The Doxyfile should be part of the (primary) configuration system. DONE
  • Perhaps it's best to define a "master-doxyfile" in the primary configuration system, containing macros or includes for the above four definitions, and then the build system builds the finale Doxyfile (in the derived configurations) in dependency on these includes/macro-definitions. (Alternatively, one can specify directly a doxyfile to be used --- how to achieve this with cmake? In the normal case, target html depends on the doxyfile to be created if necessary, but if some variable is specified on the make command line, then the doxyfile is not used.) DONE (we have the Doxyfile in Buildsystem/Configuration, and we use m4-preprocessing)
  • Allows the Doxyfile for includes or macro expansion? See "Environment-variable expansion" in Buildsystem/OKlibBuilding/Targets/html/plans/general.hpp. DONE (yes, but we use the m4-system)

Definition in file general.hpp.