OKlibrary  0.2.1.6
Internals.hpp File Reference

Internals of how the build system for external sources works. More...

Go to the source code of this file.


Detailed Description

Internals of how the build system for external sources works.

Internals of the build system for external sources

General overview

Main directories involved are:

  • The base directory for installations of external sources is /home/csoliver/OKplatform/ExternalSources (variable "ExternalSources"):
    1. The sources one finds in /home/csoliver/OKplatform/ExternalSources/sources (variable "ExternalSources_sources").
    2. The installed software then is located in /home/csoliver/OKplatform/ExternalSources/Installations (variable "ExternalSources_installations").
    3. Building the packages is done (if possible) in separate directories, which can be found in /home/csoliver/OKplatform/ExternalSources/builds (variable "ExternalSources_builds").
    4. Finally the extracted documentation is located in /home/csoliver/OKplatform/system_directories/doc/internet_html/doc/doc (variable "ExternalSources_doc").
  • The scripts etc. for building the external sources are in /home/csoliver/OKplatform/OKsystem/OKlib/Buildsystem/ExternalSources, with the following sub-directories:
    1. "SpecialBuilds" contains information on how to build the packages.
    2. The standard "systematic directories", "docus" and "plans", contain, as usual, user documentation (like this file) and plans.
    3. "sources" mirrors /home/csoliver/OKplatform/ExternalSources/sources, and contains the checksums for all external sources (obtained by the tool md5sum ).

Makefiles

  • /home/csoliver/OKplatform/OKsystem/OKlib/Buildsystem/ExternalSources/Makefile is the central makefile (invoked by the masterscript oklib).
    1. Some functions are provided for unpacking archives.
    2. The global targets, given by variable "global_targets_extsrc_okl", with value
      all clean cleanall update math buildsystem libraries compilers sat boolean math2
      are defined.
    3. Finally it includes the makefiles from /home/csoliver/OKplatform/OKsystem/OKlib/Buildsystem/ExternalSources/SpecialBuilds, each responsible for building one external source.
  • The configuration information is obtained from /home/csoliver/OKplatform/OKsystem/OKlib/Buildsystem/Configuration/ExternalSources/all.mak:
    1. The general configuration-variables regarding external sources are defined there.
    2. And via inclusion of the special makefiles, responsible for building single external sources, all special configuration information (like version numbers, package-names, etc.) is obtained.
  • For each special external source (like "git" or "gcc") there are thus two makefiles, e.g., for "git" we have /home/csoliver/OKplatform/OKsystem/OKlib/Buildsystem/Configuration/ExternalSources/git.mak for the configuration information, and /home/csoliver/OKplatform/OKsystem/OKlib/Buildsystem/ExternalSources/SpecialBuilds/git.mak for the actual build-instructions.
  • If a special index-page for the documentation is created, then this is done by /home/csoliver/OKplatform/OKsystem/OKlib/Buildsystem/OKlibBuilding/Targets/html/Makefile.

Documentation

  • In directory /home/csoliver/OKplatform/OKsystem/OKlib/Buildsystem/ExternalSources/SpecialBuilds/docus for each external source one finds a dedicated documentation-file (belonging to the Doxygen-system; for example "git.hpp").
  • Some external sources need an index-page to access documentation, and such index-pages (which do not belong to the Doxygen-system, but to the system of local html-pages) are found in directory /home/csoliver/OKplatform/OKsystem/OKlib/Buildsystem/ExternalSources/SpecialBuilds/Documentation (for example one finds there "Maxima.html").
  • The overview page on the installation of external sources is /home/csoliver/OKplatform/OKsystem/OKlib/Buildsystem/Html/Local/ExternalSources.html (again, part of the local html-system).
  • The variables for checking the status of installations are (currently) defined in /home/csoliver/OKplatform/OKsystem/OKlib/Buildsystem/Configuration/ExternalSources/tests.mak.
  • The buildsystem relies on using absolute paths to all files. To be able to build the documentation under different circumstances, in /home/csoliver/OKplatform/OKsystem/OKlib/Buildsystem/Configuration/Html/relative_paths.mak one finds definitions for paths from local html-pages to other local html-pages and to pages in /home/csoliver/OKplatform/system_directories/doc/internet_html/doc/doc.

Adding new external sources

In the following the directory /home/csoliver/OKplatform/OKsystem/OKlib/Buildsystem, containing the buildsystem for the OKlibrary, is abbreviated by "Buildsystem".

Assume that "ExS" is to be built:

  1. First in directory Buildsystem/Configuration/ExternalSources a configuration file "exs.mak" is to be created (copying an appropriate role model), and it is to be included in Buildsystem/Configuration/ExternalSources/all.mak.
  2. Then in directory Buildsystem/ExternalSources/SpecialBuilds the makefile "exs.mak" for building the source is to be created (copying an appropriate role model), and it is to be include in the makefile Buildsystem/ExternalSources/Makefile.
  3. The md5sum-hash-values of new external sources (from /home/csoliver/OKplatform/ExternalSources/sources) are stored in directory Buildsystem/ExternalSources//sources.
  4. Documentation:
    1. First the file Buildsystem/Configuration/ExternalSources/tests.mak has to be extended with test-code for ExS, copying appropriate role models.
    2. And using these variables, a docu-file has to be produced named Buildsystem/ExternalSources/SpecialBuilds/docus/ExS.hpp.
    3. This docu-file should get a link in Buildsystem/ExternalSources/docus/general.hpp.
    4. After running Doxygen (by "html"), the address of the docu-file can be entered into the configuration makefile Buildsystem/Configuration/ExternalSources/exs.mak.
    5. Finally we create an entry in the main external-sources overview page Buildsystem/Html/Local/ExternalSources.html (again, by copy-and-paste from other entries).
    6. And for the links to work new entries are added (appropriately) in Buildsystem/Configuration/Html/relative_paths.mak.
    7. If the documentation for ExS needs a dedicated index page (i.e., is not just a single link to the main documentation page), then proceed as follows:
      1. Create Buildsystem/ExternalSources/SpecialBuilds/Documentation/ExS.html, copying an appropriate role model.
      2. Add to the makefile Buildsystem/OKlibBuilding/Targets/html/Makefile an appropriate line for the respective preprocessing-call.
  5. Finally, in directory Buildsystem/ExternalSources/sources/ExS for source-files "package.extension" we have files "package.extension.md5sum", with content the output of shell> md5sum package.extension.

Some general information:

  • What are "role models"?
    1. "Role models" are files fulfilling the same purpose, for similar systems.
    2. One should use an up-to-date role model (look at the history as provided by Git).
    3. If the similar system is "SExS", then first the respective file for SExS is copied, and then (in XEmacs) globally string "sexs" is replaced by "exs" (by using lower-case we indicate that XEmacs shall take care of upper- and lower-cases).
    4. Then the resulting file has to be carefully edited.
  • Finally, it may also worth to look at previous installations, as recorded in the Git-history (we typically bundle all commits regarding for example a new installation, so that one sees all files involved).

In case of trouble

  1. See the error messages in /home/csoliver/OKplatform/system_directories/log/ExternalSources.
  2. Often some library or some tool is missing; either you can add the missing part yourself (perhaps just using the package management of your Linux distribution), or you might find it in the OKlibrary.
  3. If this doesn't help, consult the mailing list.
  4. If we can't resolve it, since it seems to depend on specialities of your system, then
    1. extract the sequence of build instruction from the makefiles;
    2. reproduce the problem independently of the OKlibrary, by using the extracted build instructions --- if the problem goes away, report back to our mailing list.
    3. Otherwise contact the support of the respective package, and ask what's wrong with the build instructions.
    4. Either you now can "repair" your own system, so that the build of the OKlibrary now works, or you report back to our mailing list.

Definition in file Internals.hpp.