OKlibrary  0.2.1.6
general.hpp File Reference

General documentation for the central makefile Buildsystem/OKlibBuilding/Makefile. More...

Go to the source code of this file.


Detailed Description

General documentation for the central makefile Buildsystem/OKlibBuilding/Makefile.

Usage

These targets are to be used together with the oklib-command (see Buildsystem/MasterScript/docus/general.hpp).

Make targets

Applications

The compilation-targets apply to the current directory and everything below.

all First call unoptimised, then call optimised.
unoptimised Compile unoptimised object files and programs (including test-programs for the old test system, but not for the new one).
optimised Compile optimised object files and programs (including test-programs for the old test system, but not for the new one).

Test system

The test-targets apply to the current directory and everything below.

The old test system (deprecated)

check First call test, then call testop.
test Perform unoptimised tests (recompiling code if necessary).
testop Perform optimised tests (recompiling code if necessary).

The new test system

new_check First call new_test, then new_testop, then maxima_test.
new_test Perform unoptimised tests (recompiling code if necessary).
new_testop Perform optimised tests (recompiling code if necessary).
maxima_test Run the tests for the Maxima/Lisp level.

Application tests

app_tests Performs (unconditionally) application tests.

Local documentation

The following targets are independent from the calling-directory.

doxygen_documentation Creates the complete doxygen-documentation.
documentation_index Creates local html index pages.
html Calls doxygen_documentation and documentation_index.

Cleaning

The cleaning-targets apply to the current directory and everything below.

Regarding the old test system

cleantest Removes the test timestamp file for the current module. The next make test will re-run the tests for the current module.
cleantestop Removes the optimised test timestamp file for the current module. The next make testop will re-run the tests for the current module.
cleanalltest Calls first cleantest, then cleantestop.

Regarding the new test system

new_cleantest Removes the test timestamp file for the current module. The next make new_test will re-run the tests for the current module.
new_cleantestop Removes the test timestamp file for the current module. The next make new_testop will re-run the tests for the current module.
new_cleanalltests Calls first new_cleantest, then new_cleantestop .
cleantestobj Removes all test object files and optimised test object files for the current module.
cleantestprograms Removes all test program executables (optimised and unoptimised) for the current module.
cleanmessages Removes error, log and message files for the current module.

General cleaning

cleanobj Removes all object files and optimised object files for the current module. This includes the object-files from the old test-system (but not for the new one).
cleandep Removes all dependency files for the current module.
clean Calls cleanobj, cleantestobj, cleandep, cleanalltest, new_cleanalltests.
cleanprograms Removes all program executables (optimised and unoptimised) for the current module. For the old test system, this includes the test-programs, but not for the new test system.
cleanall Calls clean, cleanprograms, cleantestprograms, cleanmessages.

Customisation of gcc and libraries

Compilation happens via the default version of the local gcc (i.e., the gcc provided by the OKlibrary), using the default versions of the appropriate local libraries (also provided by the OKlibrary):

The versions of gcc and for example boost can be changed as follows:

  • Either change the (local) version of boost (typically only useful in transition periods), while the build system chooses the default (local) gcc.
  • Or change the (local) version of gcc, while the build system chooses the default variant of the recommended (local) boost version, compiled with the chosen gcc-version.
  • Or change both.

The make-variables to be set on the command-line are as follows (again considering boost as an example):

gcc_recommended_version_number_okl=V Use the locally installed gcc with version V (for example gcc_recommended_version_number_okl=4.2.4); default value is the recommended version.
boost_recommended_version_number_okl=V Use the locally installed boost with version V (for example boost_recommended_version_number_okl=1_34_0); default value is the recommended version.

Examples:

  • oklib all check new_check app_tests html boost_recommended_version_number_okl=1_34_1 test_level=full
        
    is for using the specified version of the Boost-library, where we first compile everything, then run all tests, and finally create the documentation, and this all with test-level "full".

Customisation of compilation, linking and testing

By the following command-line settings compilation, linking and running tests can be influenced:

Compile_tool=T Command to prefix each call of the compiler; default value is T="time -p"
Link_tool=T Command to prefix each call of the linker; default value is T="time -p"
Test_tool=T For example T="valgrind" or T="valgrind --quiet"; default value is T="time -p"

Settings for the new test system

The basic parameters are:

test_level=L L is one of "basic", "full", "extensive" (the test effort); default is "basic"
error_level=l, message_level=l, error_level=l l is one of 0,1,2 (the level of verbosity for the three output streams); default is 0

The three output streams with their meanings:

  • The error stream contains all output related to test failures. It is set by default to
    error_stream = "cerr|ofstream-w=$(error_file)|ofstream-w=$(log_file)"
       
    that is, error output goes at the same time to standard error, to the error file, and to the log file.
  • The message stream contans all output which informs about the general sequence of tests (it is produced by the test system itself). It is set by default to
    message_stream = "cout|ofstream-w=$(message_file)|ofstream-w=$(log_file)"
       
    that is, message output goes at the same time to standard output, to the message file, and to the log file.
  • The log stream contains all output specifically produced by the test functions to inform about the tests. It is set by default to
    log_stream = "ofstream-w=$(log_file)"
       
    that is, log output only goes to the log file.

The default values for the three output files are

error_file = $(test_aux_dir)/Error
message_file = $(test_aux_dir)/Message
log_file = $(test_aux_dir)/Log
   

where the current value of configuration variable "test_aux_dir" (for this run) is /home/csoliver/OKplatform/system_directories/aux/tests/Variables.

Finally for each stream the language can be set by error_lang, message_lang and log_lang; the default value is en_GB.

Internet pages

The following targets are independent from the calling-directory.

internet_local Creates the (movable) Internet web pages first under the local doc-directory.
internet_global Moves the Internet-web-pages-directory from the local place to the "global" place.
internet_packages Moves the content of the (local) packages-directory to their "global" place.
internet Calls internet_local, internet_global and internet_packages.

Remarks:

  1. For the Internet web pages a version of the local documentation is created from scratch, with appropriate movable url's.
  2. The local directory with the (movable) Internet pages is "internet_html_dir" = /home/csoliver/OKplatform/system_directories/doc/internet_html/doc/internet_html.
  3. The directory providing the "global" place is "internet_dir" = . This variable is to be set in the configuration-override file.
  4. The local packages-directory is "packages_dir" = /home/csoliver/OKplatform/system_directories/packages, the "global" packages-directory is "internet_dir/packages".
  5. When testing the internet pages and their creation with a local web server, one can proceed as follows, using the Apache web server and testing the central ok-library-web-page:
    1. The default directory for placing web pages is /usr/local/apache2/htdocs.
    2. In this directory root creates the directory ok-sat-library, with group-ownership "users" and group-writable, but not accessible, readable or writable for "others".
    3. Now after running oklib internet (of course as a normal user) we get the Internet home page at "http://localhost/ok-sat-library/internet_html/index.html".
    4. The packages need to be created before (by oklib --create-packages).
Todo:

Complete the information on customisation.

Once the move to the new test system has been completed, references to the old test system need to be removed.

Definition in file general.hpp.