Installation procedure¶
Build documentation¶
Install the dependencies in an opam switch
$ opam switch create geneweb 4.09.1 $ opam install . --deps-only
Run the configuration script
$ ocaml ./configure.ml
Build the distibution
$ make clean distrib
Configure¶
The configure.ml
file is an ocaml script whose purpose is to
update Makefile.config
by setting the environment variables
the Makefile
needs.
usage: configure.ml [options]
--gwdb-legacy Use legacy backend
--release Use release profile: no debug informations (defaut: true)
--debug Use dev profile: no optimization, debug informations (default: false)
--sosa-legacy Use legacy Sosa module implementation
--sosa-num Use Sosa module implementation based on `num` library
--sosa-zarith Use Sosa module implementation based on `zarith` library
--syslog Log gwd errors using syslog
-help Display this list of options
--help Display this list of options
Build system¶
Makefile¶
The root of every action that could be performed on geneweb pass over its Makefile. In this section we will describe the variables, targets and its dependencies.
Variables¶
Makefile loads variables from Makefile.config generated by the configuration script for customised execution of some commands. Variables with suffix _D
are passed to cppo command that preprocess files with an equivalent to the C preprocessor. Here is a description of those variables :
OS_TYPE
: kernel name (Linux, Win, Darwin, etc.)STRIP
: command that discards symbols from compiled object files. Depends on kernel (linux command isstrip
).RM
: command that is used to remove files, directories, etc. Depends on kernel (linux command is/bin/rm -f
).EXT
: extension for geneweb executable files. Depends on kernel (on Windows it’s .exe).GWDB_D
: argument to cppo command that defines a variable that tells which geneweb data base driver implementation will be used (example : GENEWEB_GWDB_LEGACY).OS_D
: argument to cppo command that defines a variable for current system (example : UNIX).SYSLOG_D
: argument to cppo command that could define a marker variable SYSLOG. When defined, activate logging by geneweb server.GWDB_PKG
: dune library that implements geneweb database driver (example : geneweb.gwdb-legacy).SOSA_PKG
: dune library that implements sosa (example : geneweb_sosa_zarith).SYSLOG_PKG
: if SYSLOG is defined, then indicate dune library used for logging functionalities.DUNE_DIRS_EXCLUDE
: specifies directories that will be excluded from geneweb library. Used to exclude not chosen implementations for sosa and for geneweb database driver.DUNE_PROFILE
: specifies dune profile (default : release).
Makefile also defines additional non-configurable variables :
PREFIX
:DISTRIB_DIR
: directory where a local geneweb distribution is stored.BUILD_DISTRIB_DIR
: directory where geneweb executable files for local distribution are stored.BUILD_DIR
: directory where the compiled artefacts are stored.CPPO_D
: regroups all arguments to cppo (GWDB_D
,OS_D
,SYSLOG_D
). If dune’s profile is dev then also contains the definition of DEBUG variable that enables emitting warnings on stderr by geneweb server.BENCH_FILE
: file where benchmark results are stored.
Nowadays geneweb is entirely compiled by dune, due to dune files. Non-preprocessed version of dune files are stored in dune.in. Makefile is responsible for the generation of corresponding dune from the dune.in. Every dune file that should be generated is stored in variable GENERATED_FILES_DEP
in addition to other files generated by Makefile :
GENERATED_FILES_DEP = \
dune-workspace \
hd/etc/version.txt \
lib/dune \
lib/gwdb/dune \
lib/core/dune \
lib/gwlib.ml \
lib/util/dune \
benchmark/dune \
bin/connex/dune \
bin/consang/dune \
bin/fixbase/dune \
bin/ged2gwb/dune \
bin/gwb2ged/dune \
bin/gwc/dune \
bin/gwd/dune \
bin/gwdiff/dune \
bin/gwgc/dune \
bin/gwrepl/dune \
bin/gwrepl/.depend \
bin/gwu/dune \
bin/setup/dune \
bin/update_nldb/dune \
test/dune \
Targets¶
Main targets¶
Makefile.config: configure.ml
Executed when Makefile.config isn’t up-to-date with configure.ml. Prints corresponding error message and terminates execution. This target isn’t executed when the goal is
ci
target.lib/gwlib.ml:
Generates the content for lib/gwlib.ml that depends on
PREFIX
.bin/gwrepl/.depend:
Generates the content for bin/gwrepl/.depend.
hd/etc/version.txt:
Generates the content for hd/etc/version.txt that indicates some information about geneweb version like date of compilation and commit used.
%/dune: %/dune.in Makefile.config
Generates dune file from corresponding dune.in as follows:
Preprocess with
cppo -n
depending onCPPO_D
argument.Remplaces with sed occurrences of %%%CPPO_D%%%, %%%SOSA_PKG%%%, %%%GWDB_PKG%%%, %%%SYSLOG_PKG%%% and %%%DUNE_DIRS_EXCLUDE%%% by the values of corresponding variables.
dune-workspace: dune-workspace.in Makefile.config
Generates dune-workspace file that is used to define different build contexts and currently selected build profile. Generation is done by replacing the occurrence of %%%DUNE_PROFILE%%% inside dune-workspace.in by the value of corresponding variable.
build: $(GENERATED_FILES_DEP)
Default goal when
make
is called without targets. Executes the target for every file specified inGENERATED_FILES_DEP
and then build all public artefacts in geneweb package.distrib: build
Principal target. Build entire system and creates a local distibution of geneweb under
DISTRIB_DIR
directory. See for more information.clean:
Removes all generated files that are specified in
GENERATED_FILES_DEP
andDISTRIB_DIR
Additional targets¶
generated: $(GENERATED_FILES_DEP)
Executes the target for every file specified in
GENERATED_FILES_DEP
.install: $(GENERATED_FILES_DEP)
Executes the target for every file specified in
GENERATED_FILES_DEP
, compilates all public artefacts and then install geneweb in opam.uninstall: $(GENERATED_FILES_DEP)
Same as install but remote geneweb from opam.
doc: | $(GENERATED_FILES_DEP)
Generates documentation for all public artefacts in geneweb. Note that prerequisites on the right to
|
are order-only.test: | $(GENERATED_FILES_DEP)
Executes test suites defined in test directory.
bench: | $(GENERATED_FILES_DEP)
Executes the benchmark defined in benchmark directory.
bench-marshal: | $(GENERATED_FILES_DEP)
Executes the benchmark with options
--marshal --name ${BENCH_NAME} ${BENCH_FILE}
whereBENCH_NAME
is the name of bench results that will be stored in hash table and marshalled inBENCH_FILE
. Prerequisite to ci target.bench-tabulate: | $(GENERATED_FILES_DEP)
Executes the benchmark with option
--tabulate ${BENCH_FILE}
that prints on the screen tables of bench results stored inBENCH_FILE
. Prerequisite to ci target.ci:
Configure geneweb for every existing implementation of sosa.
Executes tests and benchmarks (name corresponds to sosa implementation) for each of them (recursive make call with goals clean, test, bench-marshal clean).
Prints all benchmark results (recursive make call with goal bench-tabulate).
Dune configuration files¶
dune-project¶
This file is used to mark the root of projects as well as define project-wide parameters. In the case of geneweb this file specifies version of the dune configuration files with lang
stanza and sets the name of project with name
stanza:
(lang dune 2.8)
(name geneweb)
dune-workspace¶
This file is used to define different build contexts and to select a build profile.
GeneWeb defines only one default
context. Build profile (release
or dev
) is chosen by configuration script (--release
option to use release profile) with subsequent make
.
dune¶
Dune files used to describe libraries, executables, tests, and everything dune needs to know about. Some of dune files are preprocessed by Makefile in order to remplace all occurences of %%%VARIABLE%%% by their real value (see Variables) In this section we will describe each of those file inside geneweb project.
./dune
The root dune file that, in the geneweb case, modifies the environment used with dev
build profile. Particularly, it passes additional option to the OCaml compiler :
-w +a-4-9-35-42-44-48
This option tells to compiler to enable all the warnings except :
Fragile pattern matching.
Missing fields in a record pattern.
Unused for-loop index.
Disambiguated constructor or label name.
Open statement that shadows an already defined identifier.
Implicit elimination of optional arguments.
GeneWeb library¶
lib/dune
Defines public geneweb library .
It includes modules under the
lib
directory and every of them is preprocessed withcppo
.Module TemplAst is specified as a module without implementation (has only .mli).
Module Templ_parser is obtained from templ_parser.mll with stanza
ocamllex
that makes call for ocamllex lexer.Compilation of this library includes compilation of every subdirectory (with
dirs
stanza) except those mentioned in %%%DUNE_DIRS_EXCLUDE%%% variable (not used implementations).Depends on geneweb libraries :
geneweb_core
geneweb_def
geneweb_gwdb
geneweb_sosa_mli
geneweb_util
Depends on extrenal libraries :
lib/core/dune
Defines public geneweb.core library (locally - geneweb_core).
It includes modules under the
lib/core
directory and every of them is preprocessed withcppo
.Depends on geneweb libraries :
geneweb_def
geneweb_gwdb
geneweb_sosa_mli
geneweb_util
Depends on extrenal libraries :
lib/def/dune
Defines public geneweb.def library (locally - geneweb_def). Includes only two modules : Adef and Def.
lib/gwdb/dune
Defines public geneweb.gwdb library (locally - geneweb_gwdb).
It includes modules under the
lib/gwdb
directory and every of them is preprocessed withcppo
.Depends on geneweb libraries :
geneweb_def
gwdb_driver_mli
geneweb_util
Depends on extrenal libraries :
lib/gwdb_driver.mli/dune
Defines public virtual (that requires an implementation) geneweb.gwdb_driver library (locally - gwdb_driver_mli).
Include only one virtual module Gwdb_driver.
Depends on geneweb libraries :
geneweb_def
Depends on extrenal libraries :
lib/gwdb-legacy/dune
Defines public geneweb.gwdb-legacy library (locally - gwdb_legacy). This library is an implementaion for virtual gwdb_driver_mli library.
It includes modules under the
lib/gwdb-legacy
directory.Module Dbdisk is specified as a module without implementation.
Depends on geneweb libraries :
geneweb_def
geneweb_util
Depends on extrenal libraries :
lib/json_export/dune
Defines public geneweb.export library (locally - geneweb_export).
Include only one module Json_converter.
Depends on geneweb libraries :
geneweb_def
geneweb_def_show
geneweb_gwdb
Depends on extrenal libraries :
lib/show/dune
Defines public geneweb.def_show library (locally - geneweb_def_show).
Include only one module Def_show. This module is preprocessed with ppx_import and ppx_deriving.show PPX rewriters that require feedback from the compilation phase (for that it is used inside
staged_pps
stanza rather than in ordinarpps
).Depends on geneweb libraries :
geneweb_def
geneweb_gwdb
lib/sosa.mli/dune
Defines public virtual geneweb.sosa.mli library (locally - geneweb_sosa_mli). Includes only one virtual module Sosa.
lib/sosa_array/dune
Defines public geneweb.sosa_array library (locally - geneweb_sosa_array). This library is an one of implementaions for virtual geneweb_sosa_mli library. It includes only one module Sosa.
lib/sosa_num/dune
Defines public geneweb.sosa_num library (locally - geneweb_sosa_num). This library is an one of implementaions for virtual geneweb_sosa_mli library.
It includes only one module Sosa.
Depends on extrenal libraries :
lib/sosa_zarith/dune
Defines public geneweb.sosa_zarith library (locally - geneweb_sosa_zarith). This library is an one of implementaions for virtual geneweb_sosa_mli library.
It includes only one module Sosa.
Depends on extrenal libraries :
lib/util/dune
Defines public geneweb.util library (locally - geneweb_util).
It includes modules under the
lib/util
directory and every of them is preprocessed withcppo
.Depends on geneweb libraries :
geneweb_def
Depends on extrenal libraries :
GeneWeb executables¶
bin/connex/dune
Defines public geneweb.connex executable (locally - connex).
It includes only one module Connex.
Depends on geneweb libraries :
geneweb
Chosen implementation of gwdb_driver_mli.
Chosen implementation of geneweb_sosa_mli.
Depends on extrenal libraries :
bin/consang/dune
Defines public geneweb.consang executable (locally - consang).
It includes only one module Consang that is preprocessed with
cppo
.Depends on geneweb libraries :
geneweb
Chosen implementation of gwdb_driver_mli.
Chosen implementation of geneweb_sosa_mli.
Depends on extrenal libraries :
bin/fixbase/dune
Defines public geneweb.gwfixbase executable (locally - gwfixbase).
It includes only one module Gwfixbase.
Depends on geneweb libraries :
geneweb
Chosen implementation of gwdb_driver_mli.
Chosen implementation of geneweb_sosa_mli.
Depends on extrenal libraries :
bin/ged2gwb/dune
Defines public geneweb.ged2gwb executable (locally - ged2gwb).
It includes only one module Ged2gwb preprocessed by camlp5o that provides parsing and pretty printing tools. Particulary, it uses following extensions:
pr_o.cmo
: pretty print in normal syntaxpa_extend.cmo
: syntax extension for grammarsq_MLast.cmo
: syntax tree nodes (in revised syntax)
Depends on geneweb libraries :
geneweb
Chosen implementation of gwdb_driver_mli.
Chosen implementation of geneweb_sosa_mli.
Depends on extrenal libraries :
bin/gwb2ged/dune
Defines :
Public geneweb.gwb2ged_lib library (locally - gwb2ged_lib).
It includes only one module Gwb2gedLib.
Depends on geneweb libraries :
geneweb
gwexport_lib
Public geneweb.gwb2ge executable (locally - gwb2ged).
bin/gwc/dune
Defines public geneweb.gwc executable (locally - gwc).
It includes modules under the
bin/gwc
directory and every of them is preprocessed withcppo
.Depends on geneweb libraries :
geneweb
Chosen implementation of gwdb_driver_mli.
Chosen implementation of geneweb_sosa_mli.
Depends on extrenal libraries :
bin/gwd/dune
Defines:
Public wrapped geneweb.gwd_lib library (locally - gwd_lib).
It includes modules GwdLog, GwdPlugin and Request that are preprocessed with
cppo
.Depends on geneweb libraries :
geneweb
wserver
Chosen implementation of gwdb_driver_mli.
Chosen implementation of geneweb_sosa_mli.
Public executable geneweb.gwd library (locally - gwd).
It includes modules Gwd, GwdPluginDep, GwdPluginMD5, GwdPluginMETA and Robot that are preprocessed with
cppo
.Module GwdPluginMD5 is created by
rule
stanza. Stanzadeps
tells to dune to do firstly:Find module Mk_gwdPluginMD5
Construct all recursively defined in
plugins/
aliases@plugin
. FilegwdPluginMD5.ml
is created by running maker scriptmk_gwdPluginMD5.ml
with path toplugins/
directory specified in argument.
All the libraies used by executable are compiled with
-linkall
flag.Depends on geneweb libraries :
gwd_lib
geneweb
wserver
Chosen implementation of gwdb_driver_mli.
Chosen implementation of geneweb_sosa_mli.
Depends on extrenal libraries :
bin/gwdiff/dune
Defines public geneweb.gwdiff executable (locally - gwdiff).
It includes only one module Gwdiff.
Depends on geneweb libraries :
geneweb
Chosen implementation of gwdb_driver_mli.
Chosen implementation of geneweb_sosa_mli.
Depends on extrenal libraries :
bin/gwexport/dune
Defines public geneweb.gwexport_lib library (locally - gwexport_lib).
It includes only one module Gwexport.
Depends on geneweb libraries :
geneweb
bin/gwgc/dune
Defines public geneweb.gwgc executable (locally - gwgc).
It includes only one module Gwgc that is preprocessed with
cppo
.Depends on geneweb libraries :
geneweb
Chosen implementation of gwdb_driver_mli.
Chosen implementation of geneweb_sosa_mli.
Depends on extrenal libraries :
bin/gwrepl/dune
Defines:
Private library gwrepl_deps that links all dependent libraries.
Public gwrepl executable .
It includes only two modules Gwrepl and Data.
gwrepl executable is preprocessed with
cppo
.Module Data is created with
rule
stanza from :Module Mk_data
File
.depend
.
Filedata.ml
is created by running maker scriptmk_data.ml
that is linked withunix.cma
by OCaml toplevel.
Data is preprocessed with ppx_blob that is used to extract the content of binary file at compile time.
It is compiled by bytecode compiler and producing static object files:
(modes byte object)
All the libraies used by executable are compiled with
-linkall
flag.Linked with
-custom
option that is used by bytecode compiler to produce native executable that embeds the ocamlrun virtual machine as well as the byte code. See dune-executable.Depends on external libraries:
bin/gwu/dune
Defines :
Public geneweb.gwu_lib library (locally - gwu_lib).
It includes only one module GwuLib.
Depends on geneweb libraries :
geneweb
gwexport_lib
Public geneweb.gwu executable (locally - gwu).
bin/setup/dune
Defines public geneweb.setup executable (locally - setup).
It includes only one module Setup that is preprocessed with
cppo
.Depends on geneweb libraries :
geneweb
wserver
Chosen implementation of gwdb_driver_mli.
Chosen implementation of geneweb_sosa_mli.
Depends on extrenal libraries :
bin/update_nldb/dune
Defines public geneweb.update_nldb executable (locally - update_nldb).
It includes only one module Update_nldb.
Depends on geneweb libraries :
geneweb
Chosen implementation of gwdb_driver_mli.
Chosen implementation of geneweb_sosa_mli.
Depends on extrenal libraries :
bin/wserver/dune
Defines public geneweb.wserver library (locally - wserver).
It includes only one module Wserver.
Depends on geneweb libraries :
geneweb_util
Depends on extrenal libraries :
GeneWeb plugins¶
plugins/cgl/dune
Defines plugin plugin_cgl.
It includes only one module Plugin_cgl.
Plugin is compiled by native compiler with
(modes (native plugin))
Construction of
@plugin
alias depends on plugin’s compilation.Depends on geneweb libraries :
geneweb
gwd_lib
wserver
plugins/export/dune
Defines plugin plugin_export.
It includes only one module Plugin_export.
Plugin is compiled by native compiler.
Construction of
@plugin
alias depends on plugin’s compilation.Compiled with flags that tells to compiler to disable warnings:
Innocuous unused variable.
Constructor or label name used out of scope.
Linked statically with libraries :
gwexport_lib
gwu_lib
gwb2ged_lib
Depends on geneweb libraries :
geneweb
gwd_lib
gwb2ged_lib
gwexport_lib
gwu_lib
wserver
plugins/fixbase/dune
Defines plugin plugin_fixbase.
It includes only one module Plugin_fixbase.
Plugin is preprocessed with ppx_deriving.show.
Plugin is compiled by native compiler with
-linkall
option.Construction of
@plugin
alias depends on:Plugin’s compilation
Every file from assets directory.
Depends on geneweb libraries :
gwd_lib
geneweb_def_show
plugins/forum/dune
Defines plugin plugin_forum.
It includes only one module Plugin_forum that was obtained by preprocessoing corresponding
.cppo.ml
. Stanzarule
in this context is used to remplace lines with directive#include
by one of included file :
(rule
(target plugin_forum.ml)
(deps
(:included
%{project_root}/plugins/forum/forum.ml
%{project_root}/plugins/forum/forumDisplay.ml
)
(:src plugin_forum.cppo.ml)
)
(action (run %{bin:cppo} %{src} -o %{target}))
Plugin is compiled by native compiler.
Construction of
@plugin
alias depends on plugin’s compilation.Depends on geneweb libraries :
geneweb
gwd_lib
wserver
plugins/gwxjg/dune
Defines :
Public geneweb.plugin_gwxjg_lib library (locally - plugin_gwxjg_lib).
It includes modules Gwxjg_ezgw, Gwxjg_data, Gwxjg_trans and Gwxjg_lexicon_parser.
Module Gwxjg_lexicon_parser is obtained from gwxjg_lexicon_parser.mll with stanza
ocamllex
that makes call for ocamllex lexer.Compiled with flags that tells to compiler to disable warnings:
Constructor or label name used out of scope.
Disambiguated constructor or label name.
Depends on geneweb libraries :
geneweb
Depends on external libraries :
Plugin plugin_gwxjg.
It includes only one module Plugin_gwxjg.
Plugin is compiled by native compiler with
-linkall
option.Construction of
@plugin
alias depends on:Plugin’s compilation
META file.
Linked statically with libraries :
plugin_gwxjg_lib
Depends on geneweb libraries :
gwd_lib
plugin_gwxjg_lib
plugins/jingoo/dune
Defines plugin plugin_jingoo.
It includes only one module Plugin_jingoo.
Plugin is compiled by native compiler with
-linkall
option.Construction of
@plugin
alias depends on plugin’s compilation.Linked statically with libraries :
Depends on geneweb libraries :
gwd_lib
plugins/lib_show/dune
Defines plugin plugin_lib_show.
It includes only one module Plugin_lib_show.
Plugin is compiled by native compiler with
-linkall
option.Construction of
@plugin
alias depends on plugin’s compilation.Linked statically with libraries :
geneweb_def_show
plugins/no_index/dune
Defines plugin plugin_no_index.
It includes only one module Plugin_no_index.
Plugin is compiled by native compiler.
Construction of
@plugin
alias depends on plugin’s compilation.Depends on geneweb libraries :
geneweb
gwd_lib
wserver
plugins/v7/dune
Wrapped plugin_v7_lib library.
It includes modules starting with prefix
V7
.Depends on geneweb libraries :
geneweb
geneweb_util
gwd_lib
Plugin plugin_v7.
It includes only one module Plugin_v7.
Plugin is compiled by native compiler with
-linkall
option.Construction of
@plugin
alias depends on:Plugin’s compilation
Every file from assets directory.
Linked statically with libraries :
plugin_v7_lib
Depends on geneweb libraries :
gwd_lib
plugin_v7_lib
plugins/v7_im/dune
Wrapped plugin_v7_im_lib library.
It includes only one module V7_im_sendImage.
Depends on geneweb libraries :
geneweb_util
gwd_lib
Plugin plugin_v7.
It includes only one module Plugin_v7_im.
Plugin is compiled by native compiler.
Construction of
@plugin
alias depends on plugin’s compilation.Linked statically with libraries :
plugin_v7_im_lib
Depends on geneweb libraries :
gwd_lib
plugin_v7_im_lib
plugins/welcome/dune
Defines plugin plugin_welcome.
It includes only one module Plugin_welcome.
Plugin is compiled by native compiler with
-linkall
option.Construction of
@plugin
alias depends on:Plugin’s compilation.
Every file from assets directory.
META file.
Depends on geneweb libraries :
gwd_lib
wserver
plugin_v7_lib
GeneWeb tests¶
test/dune
Defines:
dummy_gwdb library that is an implementation for gwdb_driver_mli virtual library.
It includes only one module Gwdb_driver.
Depends on geneweb libraries:
geneweb_def
Depends on external libraries:
test executable.
It includes modules starting with prefix
Test
that are preprocessed with ppx_deriving.show PPX rewriter.Construction of
@runtest
alias depends on execution of test.Depends on geneweb libraries:
geneweb
dummy_gwdb
Chosen implementation of geneweb_sosa_mli.
Depends on external libraries:
GeneWeb benchmarks¶
benchmark/dune
Defines bench executable.