OKlibrary  0.2.1.6
general.hpp File Reference

Documentation on the program for executing build-actions. More...

Go to the source code of this file.


Detailed Description

Documentation on the program for executing build-actions.

The masterscript "oklib"

The underlying algorithm

Calls to oklib depend on the calling directory:

  • Starting with the calling directory, all directories on the path to the enclosing OKplatform-directory (defined by having a .oklib subdirectory) are considered, and the first time a directory D is recognised defines this directory as determinative for the makefile to call:
    1. If D is "ExternalSources" then external sources building (see Buildsystem/ExternalSources/docus/general.hpp) is invoked.
    2. If D contains a file "definitions.mak" then the generic makefile for compiling the components of the library is invoked (see Buildsystem/OKlibBuilding/docus/general.hpp).
    3. If D is "OKlib" then a recursive makefile is invoked, calling the generic makefiles at lower levels.
    4. If D is "OKsystem" then another recursive makefile is invoked, this time designed to call different types of makefiles for the different repositories placed at OKsystem-level.
    5. At OKplatform-level currently there are no build-actions (other than given by the options below).
  • If you are in a different directory than the one from which you want to call oklib, but you do not want to change the working directory, then use (cd target-directory; oklib).

Options

  • --version
  • --setup
    1. Only used for initialisation.
    2. Calls the set-up makefile (${buildsystem_dir}/SetUp.mak) with trailing arguments (creating the .oklib-directory at OKplatform-level) .
  • --prebuild
    1. Used to update the directory-structure and especially to update links.
    2. Calls the prebuild-makefile (/home/csoliver/OKplatform/OKsystem/OKlib/Buildsystem/Makefile) with target "prebuild" in case no further arguments are supplied, and otherwise with trailing arguments (as targets).
    3. Target "prebuild" comprises the sub-targets "make_directories", "create_links" and "create_public_links", for
      1. creating basic directories;
      2. creating makefile-links;
      3. creating links to the main executables produced by the OKlibrary (in /home/csoliver/OKplatform/bin).
    4. The target "clean_links" removes all makefile-links.
  • --maxima
    • Configures and calls Maxima; see ComputerAlgebra/docus/Maxima.hpp.
    • Further arguments are passed to Maxima.
    • The initialisation file is /home/csoliver/OKplatform/ExternalSources/Installations/Maxima/ecl/5.29.0/share/maxima/5.29.0/share/maxima-init.mac (managed by the OKlibrary).
    • The environment variable HOME is set to /home/csoliver/OKplatform/ExternalSources/Installations/Maxima/ecl/5.29.0.
    • In this directory in file ".maxima_history" the command-line history is stored when using Ecl (while yet for CLisp we do not use "rlwrap", and thus no command-line history is available).
    • While for all Lisps in sub-directory ".maxima" created binaries are stored.
  • --R
    • Calls R; see Buildsystem/ExternalSources/SpecialBuilds/docus/R.hpp.
    • The details of the invokation are as follows:
      • The standard parameters are --save --no-restore-data.
      • While R_PROFILE is set to /home/csoliver/OKplatform/ExternalSources/Installations/R/Rprofile_okl.
      • So the command-history is stored in file ".Rhistory" in the calling directory.
      • And in file ".RData" in the calling directory the workspace of the last session is stored, though it is not restored for new sessions.
      • While by a file ".Rprofile" in the calling directory additional initialisation instruction can be performed (after the initialisation provided by the OKlibrary, which uses R_PROFILE as mentioned above).
    • If however further parameters are given as part of the oklib-call, then R is called with just these parameters (while still setting R_PROFILE as above).
    • Finally, via --Rr (which ignores further parameters) the workspace of the last session is restored (while the user is asked whether on exit the workspace shall be saved).
  • Push and pull for oklib-repositories (where the public repository is http://github.com/OKullmann/oklibrary):
    1. --push-developer arguments pushes to the public repository, transferring arguments to the git-command. Note that pushing to the public repository is only possible if write-access has been granted.
    2. --pull-public arguments pulls from the public repository, transferring arguments to the git-command. Note that the branch-name is required as an argument, if git has not been configured otherwise.
    3. --push-ssh remote-machine remote-OKplatform-dir arguments pushes via ssh to an arbitrary OKlibrary-repository. If "remote-OKplatform-dir" contains for example "~" (for the home directory), then it is to be put in quotation marks. The "remote-machine" must be of the form "user@machine" if the username on the remote machine is different.
    4. --pull-ssh remote-machine remote-OKplatform-dir arguments pulls via ssh from an arbitrary OKlibrary-repository. If "remote-OKplatform-dir" contains characters only meaningful on the remote machine, then it is to be put in quotation marks. The "remote-machine" must be of the form "user@machine" if the username on the remote machine is different.
  • --create-package calls the ReleaseProcess makefile with trailing arguments, creating three packages in the directory given by variable packages_dir (current value is /home/csoliver/OKplatform/system_directories/packages), one basic, one including documentation, and one full package including the external sources. Special settings (supplied as parameters) are:
    1. With ExternalSources="" the additional creation of the full package (including external sources) is disabled.

Otherwise all targets are delegated to the respective makefiles. Output is logged as follows:

  • In the anchor directory .oklib one finds a symbolic link log, whose default value is /home/csoliver/OKplatform/system_directories/log.
  • When building external sources, error output is copied to log/ExternalSources.
  • Otherwise all output is copied to log/OKlibBuilding.

Setting of configuration variables:

  • If configuration is needed, for example using Maxima with a different Lisp, then specify the corresponding make-variables before the oklib call (on the command-line), e.g.
    OKplatform> maxima_lisp_name_okl=clisp oklib --maxima
    
  • In case oklib invokes a make-file, and thus all parameters are passed to the make-process, in principle configuration-variables can be also placed as arguments of oklib, however if the string has spaces in it, then the quotes will break if not doing tricky things. So also here specifying the configuration-variable(s) as environment-variable before the oklib-call is needed, e.g.:
    OKsystem> Test_tool="valgrind --quiet" oklib all check new_check app_tests html test_level=full
    

Definition in file general.hpp.