% file appendix-bm.tex, which is \input from bismon-doc.tex
% see https://github.com/bstarynk/bismon for more about Bismon

% https://tex.stackexchange.com/a/226497/42406

\begin{appendices}


\section{Building \texttt{bismon} from its source code}
\label{sec:building-bismon}

We focus here on how to build \texttt{bismon} from its source code on
\href{http://debian.org/}{Debian}-like distributions running on x86-64
computers, such as
\href{https://www.debian.org/releases/stable/}{Debian Buster 10.6}, or
\href{https://ubuntu.com/}{Ubuntu 20.04}, or
\href{https://linuxmint.com/}{Linux Mint 20}. Familiarity with the
command line is required\footnote{For example, the reader is expected
  of being able to build \href{https://www.gnu.org/software/make/}{GNU
    make} or \href{https://www.gnu.org/software/bash/}{GNU bash} from
  their source code.}, with \texttt{root} access (e.g. using
\texttt{sudo}). Fluency with \href{https://git-scm.com/}{\texttt{git}}
is expected, and it is strongly advised to \texttt{git commit} every
few hours (including your persistent store, when \texttt{bismon} is
\emph{not running}).

The reader is expected to be authorized (by his/her management, if
that build is done professionally) to build \texttt{bismon} from its
source code and probably also some recent
\href{https://gcc.gnu.org/}{GCC} cross-compiler on his/her Linux workstation
and should budget several days of work for that.


We use violet Courier font like {\textcolor{violet}{\texttt{echo this}}}
to typeset literal or sample commands to be typed in a terminal
emulator.
  
{\large Be aware that \textbf{\texttt{bismon} requires specifically some
  \href{https://gcc.gnu.org/gcc-10/}{GCC 10} compiler} and won't work
  with e.g. a GCC 9 compiler.}


If you have to build GCC 10 from its source code, take into account the following advices:

\begin{itemize}

\item if your distribution has some slightly older version of
  \texttt{gcc}, get all the build dependencies of that package[s]. On
  Debian or Ubuntu, that means running as root some command similar to
  {\textcolor{violet}{\texttt{aptitude build-dep gcc-9 g++-9}}... Of
    course replace the \texttt{9} by your particular version of
    \textit{GCC}.

\item run {\textcolor{violet}{\texttt{gcc -v}}} and write on paper the
  output. It will inspire the configuration command you will have to
  run later. If the output does not mention \texttt{--enable-plugin}
  you need to recompile GCC. If the version is not GCC 10, you also
  need to recompile GCC. Otherwise, you could use your system's GCC.

\item the GCC compiler needs to be built \textit{outside of its source tree}. Practically speaking, you should:
  \begin{enumerate}
  \item download some \texttt{gcc-10.2.0.tar.xz} file (into
    \texttt{/tmp/} ...) from a mirror site close to your geographical
    location (probably check its integrity using \texttt{sha512sum}).
  \item extract that tarball: {\textcolor{violet}{\texttt{tar xvf /tmp/gcc-10.2.0.tar.xz}}}
    in some existing writable directory (you should not be root), for example your \texttt{\$HOME/gnu/} directory. You'll need
    about a gigabyte of disk space for that source code with more than
    a hundred thousands inodes. You'll get a fresh \texttt{gcc-10.2*}
    source directory.
  \item create a fresh build directory, e.g. \texttt{MyGCC-10-Build},
    using some \texttt{mkdir MyGCC-10-Build} command from the
    \textit{parent} directory (same example: from your
    \texttt{\$HOME/gnu/} directory, but \textbf{not} from
    \texttt{\$HOME/gnu/gcc-10.2}...).
  \item Read carefully the \href{https://gcc.gnu.org/install/}{Installing GCC} chapter.
    Read it several times (the URL is \href{https://gcc.gnu.org/install/}{gcc.gnu.org/install/}).
  \item Take some rest if needed, and whatever nutriment is the best
    to raise your attention (a cup of tea, coffee, etc...)
  \item Configure with great care your GCC compiler from inside
    {MyGCC-10-Build}... You'll certainly want the
    \texttt{--enable-plugin --enable-languages=c,c++,jit
      --enable-host-shared} options to
    \texttt{\$HOME/gnu/gcc-10.2/configure} and you probably want more
    of them. That configure step lasts a few seconds, but is lazy
    (most of the configuration would happen later).
  \end{enumerate}
  
\end{itemize}

\medskip

The build procedure happens in two phases:

\begin{itemize}

\item a \textbf{configuration step}, to be run only once in a while,
  or when your Linux distribution has changed or upgraded, or when you
  have added extra useful libraries, or have upgraded your GCC
  compiler.

\item a \textbf{compilation step}, to be run more frequently
  (e.g. every night using
  \href{https://man7.org/linux/man-pages/man1/crontab.1.html}{\texttt{crontab(1)}}....)

\end{itemize}

\medskip

\subsection{Prerequisites for building \texttt{bismon}}
\label{subsec:prereq-bismon}

The \texttt{bismon} source code is on
\href{https://github.com/bstarynk/bismon/}{\texttt{\textbf{github.com/bstarynk/bismon/}}}
and the reader is expected to be capable of getting that source code
on his/her Linux workstation. A possible command to retrieve that code
might be \texttt{git clone https://github.com/bstarynk/bismon.git} ;
you'll then obtain a \emph{fresh} \texttt{bismon/} subdirectory
containing the source code. About 100Mbytes of disk space (for less
than 2000 inodes) is required.

A recent \texttt{libonion} library\footnote{This is an open source
  library for web HTTP and HTTPS service. It is LGPL licensed.}
(version 0.8 at least) is required. Fetch \texttt{libonion}'s source
code from
\href{https://github.com/davidmoreno/onion}{\texttt{\textbf{github.com/davidmoreno/onion/}}}
and follow its build instructions: probably \texttt{mkdir \_build} then
\texttt{cd \_build} then \texttt{cmake ..} then \texttt{make} and at
last \texttt{sudo make install}. That \texttt{libonion} library needs
less than 25Mbytes of disk space,
\href{https://cmake.org}{\texttt{cmake}} and several libraries (in
particular support for \texttt{openssl}, \texttt{gcrypt},
\texttt{systemd}, \texttt{sqlite3}, \texttt{lzma}, \texttt{libicu},
\texttt{libpam}) to be built. Check and inspect your
\texttt{onion/version.h} header file\footnote{You might use
  \href{https://man7.org/linux/man-pages/man1/locate.1.html}{\texttt{locate(1)}}
  or
  \href{https://man7.org/linux/man-pages/man1/find.1.html}{\texttt{find(1)}}
  to find files on your Linux box. On \emph{my} Linux machine, that
  header file is in \texttt{/usr/local/include/onion/version.h} and
  comes from \emph{libonion}
  \href{https://github.com/davidmoreno/onion/commit/43128b03199518d4878074c311ff71ff0018aea8}{git
    commit \texttt{43128b031995}}....}, it should have some
\texttt{ONION\_VERSION} close to \texttt{0.8.150} at least.

The \href{https://www.gnu.org/software/readline/}{GNU readline}
(GPLv3+ licensed) library is required, at version 8. It is useful for
autocompletion abilities in interactive situations.

Ian Lance Taylor's
\href{https://github.com/ianlancetaylor/libbacktrace}{libbacktrace}
library is needed for backtraces on error and in warnings, and
possibly for future (generated) introspective code. This library takes
advantage of \href{https://en.wikipedia.org/wiki/DWARF}{DWARF}
debugging metadata in object files and executable, so it is advised to
compile every \emph{Bismon} source file (either handwritten or
generated) with \texttt{-g} (and possibly also \texttt{-O2} for
optimization) flag to \texttt{gcc} or \texttt{g++}.


The \emph{Bismon} project \index{build!automation} uses internally \href{https://www.gnu.org/software/make/}{GNU \texttt{make}},
  version 4.2 at least. Our hand-written \texttt{GNUmakefile} is
  driving it.
  
\subsection{File naming conventions in \texttt{bismon}}

By our conventions, files \index{file} \index{naming!conventions}
whose base name\footnote{In the sense of the
\href{https://man7.org/linux/man-pages/man1/basename.1.html}{\texttt{basename(1)}}
command applied to the file path.} start with a single underscore
(that is, a \textbf{\texttt{\_}} character) are generated: for example
\texttt{\_bismon-config.mk} and \texttt{\_bm\_config.h},
etc... However, some of them need to be kept, backed-up and version
controlled but would be regenerated by running
\index{make@\texttt{make}} \index{redump@\texttt{redump}}
\index{bismon-config@\texttt{\_bismon-config.mk}}
\index{bm-config@\texttt{\_bm\_config.h}} \texttt{make redump}.

File names whose base name start with two underscores, such as
\texttt{\_\_timestamp.c}, are temporary and can be removed. They would
be removed by running \texttt{make clean} or \texttt{make
  distclean}.
\index{clean@\texttt{clean}} 
\index{distclean@\texttt{distclean}} Of course,
\href{https://en.wikipedia.org/wiki/Object_file}{object file}s
\index{object!file}
(suffixed \texttt{.o}) and
\href{https://en.wikipedia.org/wiki/Library_(computing)#Shared_libraries}{shared
  libraries} (suffixed \texttt{.so}, see
\index{library!shared}
\cite{Drepper:2011:sharedlib}) are also temporary, and could be
removed then regenerated. Some of these (in particular under
\texttt{modubin/} directory) are
\index{modubin@\texttt{modubin/}} 
\href{https://man7.org/linux/man-pages/man3/dlopen.3.html}{\texttt{dlopen(3)}}-ed.

The main executable is named \texttt{bismon}. But
\texttt{BM\_makeconst} and \texttt{BISMON-config} are auxiliary
metaprograms (generating C or C++ code). All three are
\href{https://en.wikipedia.org/wiki/Executable_and_Linkable_Format}{ELF}
executables.

\medskip

\subsection{Naming conventions and source files organization for \texttt{bismon}}

\medskip

{\large \textbf{naming and coding conventions in hand-written \emph{C} code}}

\begin{itemize}

  \item \textbf{All} public
    \href{https://en.wikipedia.org/wiki/Executable_and_Linkable_Format}{ELF}
    \index{ELF}
    \textbf{names of hand-written functions or global variables} (as
    known to
    \href{https://man7.org/linux/man-pages/man1/nm.1.html}{\texttt{nm(1)}},
    \href{https://man7.org/linux/man-pages/man1/objdump.1.html}{\texttt{objdump(1)}}
    or to
    \href{https://man7.org/linux/man-pages/man3/dlsym.3.html}{\texttt{dlsym(3)}}
    \textbf{are conventionally suffixed by}
           {\texttt{\textbf{\_BM}}}\,. For example, we have some
           \texttt{prime\_above\_BM} function giving some prime number
           above a given reasonable positive integer.

         \item \textbf{We have conventional suffixes:} Our public
           \index{suffix!file} \texttt{struct}-s are generally tagged
           with a name ending with {\texttt{\textbf{\_stBM}}}\,; Our
           \texttt{typedef}-ed types are suffixed with
                  {\texttt{\textbf{\_tyBM}}}\,; usually their field
                  names is globally unique and share a common prefix
                  (e.g. in \texttt{struct parstoken\_stBM} field names
                  all start with \texttt{tok}). Public signatures
                  (useful for C function pointers) are suffixed with
                  {\texttt{\textbf{\_sigBM}}}\, (for example, the
                  initialization of generated modules is a C function
                  of signature \texttt{moduleinit\_sigBM}\,). Most
                  public \texttt{enum}-s have their name ending with
                  {\texttt{\textbf{\_enBM}}}\,
                  e.g. \texttt{space\_enBM} for space numbers.

              \item Preprocessor symbols or macros are in all capital
                ending with {\texttt{\textbf{\_BM}}}\,, notably the
                important \texttt{LOCALFRAME\_BM} variadic macro for
                \index{localframe-bm@\texttt{LOCALFRAME\_BM} macro}
                local roots known to our garbage collector.
\end{itemize}

{\large \textbf{Hand-written \emph{C} code files}}

\begin{itemize}
  \item The header file \texttt{bismon.h} is our
    \index{bismon-h@\texttt{bismon.h} header} only public header file,
    and is \texttt{\#include}d everywhere. It includes system headers
    (e.g. \texttt{<unistd.h>} or \texttt{<pthread.h>}, and the
    following ``internal'' headers:
    \begin{enumerate}
      \item \texttt{cmacros\_BM.h} is \texttt{\#define}-ing important
        \index{cmacro-h@\texttt{cmacros\_BM.h} header} global
        preprocessor macros, including \texttt{FATAL\_BM} for fatal
        errors, \texttt{LOCALFRAME\_BM} variadic macro for local
        roots, \texttt{DBGPRINTF\_BM} for debugging output,
        \texttt{WARNPRINTF\_BM} for warning messages,
        \texttt{INFOPRINTF\_BM} for informational messages, etc... The
        \texttt{ROUTINEOBJNAME\_BM} macro
        \index{fatal-bm@\texttt{FATAL\_BM} macro}
        \index{dbgprintf-bm@\texttt{DBGPRINTF\_BM} macro}
        \index{warnprintf-bm@\texttt{WARNPRINTF\_BM} macro}
        \index{infoprintf-bm@\texttt{INFOPRINTF\_BM} macro}
        \index{routineobjectname-bm@\texttt{ROUTINEOBJNAME\_BM} macro}
        is giving the routine name of \index{objid} a given
        \textit{objid}.

      \item \texttt{id\_BM.h} is implementing
        \index{id-bm@\texttt{id\_BM.h} header} our object ids.

      \item \texttt{types\_BM.h} is defining our global types,
        \index{type-bm@\texttt{types\_BM.h} header} 
        \index{value-tybm@\texttt{value\_tyBM} opaque types} 
        \texttt{struct}-s, etc... Notice the \texttt{value\_tyBM}
        opaque type (a \texttt{void*} pointer) for Bismon values.

        \item \texttt{global\_BM.h} is declaring our \texttt{extern}al
          \index{global-bm@\texttt{global\_BM.h} header} global data,
          some of which is generated. \index{data!global}
        \item \texttt{fundecl\_BM.h} is declaring our global
          \index{fundecl-bm@\texttt{fundecl\_BM.h} header}
          \index{function} hand-written functions. Some of them are
          \texttt{static inline} for efficiency reasons (for example
          \index{elapsertime-bm@\texttt{elapsedtime\_BM.h} function}
          \index{valhash-bm@\texttt{valhash\_BM} function}
          \index{time!elapsed} \index{hash!of values}
          \texttt{elapsedtime\_BM} returning the elapsed clock time as
          a \texttt{double} number in seconds, or \texttt{valhash\_BM}
          to compute the hash code of a Bismon value.

        \item \texttt{inline\_BM.h} is implementing our global \texttt{static
            inline} functions.
          \index{inline-bm@\texttt{inline\_BM.h} header}
          \index{function!inline}
    \end{enumerate}

  \item \texttt{agenda\_BM.c} is implementing our agenda
    \index{agenda} with tasklets \index{tasklet} (see \S
    \ref{subsec:multithreadist} above).
          \index{agenda-bm@\texttt{agenda\_BM.c} file}

  \item \texttt{allocgc\_BM.c} is implementing low-level memory
          \index{allocgc-bm@\texttt{allocgc\_BM.c} file}
    allocation and garbage collector \index{garbage collector} (see \S
    \ref{subsec:gcvalobj} above).
  
  \item \texttt{assoc\_BM.c} is implementing associative lists and
          \index{assoc-bm@\texttt{assoc\_BM.c} file} \index{list!associative}
    tables, \index{object} \index{attribute} \index{association} in
    particular for object attributes.

  \item The \texttt{code\_BM.c} file contains many Bismon routines for
          \index{code-bm@\texttt{code\_BM.c} file} \index{routine}
    \index{closure} closures.

  \item The \texttt{dump\_BM.c} file is implementing the \index{dump} dump of the
    persistent store. \index{persistence} \index{store} See \S
    \index{dump-bm@\texttt{dump\_BM.c} file}
      \ref{subsec:persistence}.

  \item The \texttt{emitcode\_BM.c} file contains many Bismon routines
    for \index{emission} emission or \index{generation} of C code in
    \index{emitcode-bm@\texttt{emitcode\_BM.c} file}
    \index{module} modules.

  \item The \texttt{engine\_BM.c} file is related to \index{tasklet} tasklets 
    \index{engine-bm@\texttt{engine\_BM.c} file} in the agenda (see \S
    \ref{subsec:multithreadist} above).

  \item \texttt{gencode\_BM.c} is related
    \index{gencode-bm@\texttt{gencode\_BM.c} file} to C code
    generation. \index{code!generation} \index{generation!of code}

  \item \texttt{id\_BM.c} implements objid \index{objid}
    \index{id-bm@\texttt{id\_BM.c} file} support.

  \item \texttt{jsonjansson\_BM.c} is for JSON \index{JSON}
    \index{jsonjansson-bm@\texttt{jsonjansson\_BM.c} file} support.
    values.

  \item \texttt{list\_BM.c} is for list \index{value!list}
    \index{list-bm@\texttt{list\_BM.c} file}  values.

  \item \texttt{load\_BM.c} is for loading the persistent store
    \index{load-bm@\texttt{load\_BM.c} file} 
  \index{load} \index{persistence}.

  \item \texttt{main\_BM.c} has the \texttt{main} function 
    \index{main-bm@\texttt{main\_BM.c} file} and support functions (fatal errors, etc...).

  \item \texttt{node\_BM.c} implements node values. \index{node-bm@\texttt{node\_BM.c} file}
    \index{value!node}

  \item \texttt{object\_BM.c} implements
    objects. \index{object-bm@\texttt{object\_BM.c} file}
    \index{object} \index{value!object}

  \item \texttt{parser\_BM.c} implements the parser
    \index{parser-bm@\texttt{parser\_BM.c} file} with callbacks
    \index{callback!parser}

  \item \texttt{primes\_BM.c} contains an array of prime numbers,
    \index{primes-bm@\texttt{primes\_BM.c} file} and related
    utilities. They could be useful in hash tables \index{hash table}
    and in some hash functions. In several cases,
    \href{https://en.wikipedia.org/wiki/Flexible_array_member}{flexible
      array members} inside \textsc{Bismon} are allocated with a prime
    number size. \index{prime} \index{member!flexible array}
    \index{flexible-array@flexible array member}

  \item \texttt{scalar\_BM.c} implements scalar values
    \index{value!string} \index{string} \index{double!boxed}
    \index{value!double}
    numbers. \index{scalar-bm@\texttt{scalar\_BM.c} file} (strings,
    boxed doubles).

  \item \texttt{sequence\_BM.c} implements sets and
    tuples.\index{sequence-bm@\texttt{sequence\_BM.c} file}

  \item \texttt{user\_BM.c} relates
    \index{user-bm@\texttt{user\_BM.c} file} to reifications of
    contributors and \index{contributor} users.

  \item \texttt{misc\_BM.cc} is a \textbf{C++} file,
    \index{misc-bm@\texttt{misc\_BM.cc} file} to take advantage of
    some standard C++ \index{C++} \index{container!C++} containers.
\end{itemize}

{\large \textbf{The persistent store}}

The persistent data (see \S \ref{sec:datapersist} above) sits in files
\index{persistent!store} \index{store!persistent}
\index{store-bm@\texttt{store*BISMON.bmon} files} \texttt{store*BISMON.bmon}
(using
\href{https://man7.org/linux/man-pages/man7/glob.7.html}{\texttt{glob(7)}}
notation); more precisely

\begin{itemize}

\item \texttt{store{1}-BISMON.bmon} is for predefined objects. The header file
  \index{genbm-predef@\texttt{genbm-predef} file}
  \texttt{\_genbm\_predef.h} is generated from them at dump time. It should be version-controlled.

\item file \texttt{store{2}-BISMON.bmon} contains the global object space. Several
  global objects describe modules whose C code is generated (e.g. at
  dump time) \index{dump} \index{module} under sub-directory
  \index{modules-dir@\texttt{modules/} directory}
  \textbf{\texttt{modules/}}\,.

\item other \texttt{store\textcolor{blue}{\textbf{\textit{i}}}-BISMON.bmon}
  textual files contain\footnote{So there cannot be any
    \texttt{store{0}-BISMON.bmon} file, since space 0 is for transient objects
    which are never dumped.}  objects in space ranked $i$ \ldots. Notice
  that all these files are both loaded and dumped, and should be
  backed-up (like the \textbf{\texttt{modules/}}\, directory)
  regularily.

\end{itemize}

These \emph{generated} textual
  \index{storei-bm@\texttt{store\textit{i}-BISMON.bmon} files}
\texttt{store\textcolor{blue}{\textit{\textbf{i}}}-BISMON.bmon} \emph{files}
should be \emph{version controlled} by the
\index{git@\texttt{git}}
\href{https://git-scm.com/}{\texttt{git}} tool. You might use the \texttt{make
  redump} command to regenerate the persistent store and the modules,
and it is advised\footnote{Once \texttt{make redump} fails, the
  persistent store is inconsistent and corrupted. This should not
  happen, but when it does, use
  \href{https://git-scm.com/docs/git-bisect}{\texttt{git bisect}} to
  find the latest consistent state of your \textit{Bismon} repository.}
to run it daily.
  
{\large \textbf{Users and contributors related files}}

The \textsc{Bismon} system does need some minimal data about
users. The reader of this report is expected to verify (perhaps with
the help of lawyers) that such data is compliant and compatible with
regulations like the European \index{GDPR} GDPR.

\begin{itemize}
\item the textual file \texttt{contributors\_BM} describes the
  known\index{contributors-bm@\texttt{contributors\_BM} file}
  contributors to the \textsc{Bismon} software. That file has comments
  (or ignored lines) starting with the \texttt{\#}
  character. Non-comment lines contain three or four fields, separated
  by semi-colons (i.e. \texttt{;}):

  \begin{enumerate}
  \item the user or contributor name, as known to the system. It could be some pseudo.
  \item the unique objid of the \textsc{Bismon} object describing that user or contributor
  \item the email of that user.
  \item an optional email alias of the same user
  \end{enumerate}


\item the textual file \texttt{passwords\_BM} associates an objid with
  some encrypted password.
  known\index{passwords-bm@\texttt{passwords\_BM} file} This is used
  for the login form of the web interface, and should not be readable
  by group or others. Lines inside this files are either comments (or
  ignored lines) starting with the \texttt{\#} character, or entry
  lines with a user name, then a semicolon, then the objid, then a
  semi-colon, then the encrypted password.

\end{itemize}

Since the main author of this draft report is known to the \textsc{Bismon} system
and reified in the object of objid \\
\texttt{\_6UYrSn7piPM\_3eYhLtoXl},
the required file \texttt{contributors\_BM} should at least contain a line like
perhaps\\ {\parbox{8cm}{{\relsize{-1.3}{ \texttt{Basile
      Starynkevitch;\_6UYrSn7piPM\_3eYhLtoXlmL;b.star@email.invalid;bstarynk@localhost}}}}}

It is preferable to run the \texttt{./bismon} software with specific
command lines argument to update the contributors file and the
passwords file. A valid password should contain letters, digits, and punctuation and should have at least 10 characters, for example \texttt{foo+1234PAS}. To change the password of contributor \texttt{Basile Starynkevitch} to that, you could run :\\
\verbatim{echo Basile Starynkevitch:foo+1234PAS | ./bismon  --bismon-add-passwords=- --batch --dump=.}. Of course any serious sysadmin will avoid doing so, and write some script instead.

\subsection{Generators and meta-programs in \texttt{bismon}}

\textcolor{brown}{\textbf{Generating code is one of the core ideas of \textsc{Bismon}}}. Such code
generation happens both at build time and at run time. The generated
code is usually some C file\footnote{With additional funding and more
time, we could have used
\href{https://gcc.gnu.org/onlinedocs/jit/}{\texttt{libgccjit}} to
generate directly some \texttt{*.so} shared object.}.

At build time, two meta-programs and some shell or GNU awk scripts are involved; each of these two metaprograms has a
single handwritten C++ source code file:

\begin{itemize}
  \item \texttt{BISMON-config}
    \index{bismon-config@\texttt{BISMON-config} metaprogram} is
    querying some parameters from the user (that is the Linux sysadmin
    installing \texttt{bismon}) and generates some C++ files.

  \item \texttt{BM\_makeconst}
    \index{bm-makeconst@\texttt{BM\_makeconst} metaprogram} is usually
    scanning some handwritten C file (for example, our
    \texttt{engine\_BM.c} file, etc...)  and producing some headers or
    utility files.

  \item \texttt{timestamp-emit.sh} is a shell script
    \index{timestamp-emit.sh@\texttt{timestamp-emit.sh} shell script}
    (using internally the \texttt{emit-git-sources.gawk} GNU gawk
    script)
    \index{emit-git-sources.gawk@\texttt{emit-git-sources.gawk}
      internal \textsc{gawk} script} which emits a simple C file
    (containing only data) with the timestamp and some metadata
    information about the build.
    
\end{itemize}

But once the \texttt{bismon}
\href{https://en.wikipedia.org/wiki/Executable_and_Linkable_Format}{ELF}
executable exists, the above metaprograms are not useful
anymore. However, they are needed to recompile \texttt{bismon} (which
you might want to do periodically, i.e. every evening).

\medskip

At run time, the \texttt{bismon} executable is routinely generating C
or C++ code. Some C code (under the \textbf{\texttt{modules/}}\,
directory) is generated to extend the behevior of \texttt{bismon}
itself : the generated C code is compiled, and the resulting shared
object is
\href{https://man7.org/linux/man-pages/man3/dlopen.3.html}{\texttt{dlopen(3)}}-ed
but never\footnote{Not \texttt{dlclose}-ing is of course some kind of
\href{https://en.wikipedia.org/wiki/Memory_leak}{memory leak}, since
the \href{https://en.wikipedia.org/wiki/Virtual_address_space}{virtual
  address space} of the process running \texttt{bismon} is never
shrinking.. This explains why the \texttt{bismon} process should be
restarted at least daily.  Our
\href{https://github.com/bstarynk/misc-basile/blob/master/manydl.c}{\texttt{manydl.c}}
program demonstrates that
\href{https://man7.org/linux/man-pages/man3/dlopen.3.html}{\texttt{dlopen(3)}}-ing
many thousands of times is practically possible on modern
\textsc{Linux} workstations.}
\href{https://man7.org/linux/man-pages/man3/dlclose.3.html}{\texttt{dlclose(3)}}-ed.

\index{file!generated} \index{generation!of files} Conventionally, we
want the generated persistent files to contain the
\texttt{\textsection{GENERATED\_PERSISTENT}\textsection} string, and
\index{generated-persistent@\texttt{\textsection{GENERATED\_PERSISTENT}\textsection}}
if possible to have a \texttt{\textsection} inside the file path.  But
generated temporary (or transient) files should contain the
\texttt{\textcurrency{GENERATED}\textcurrency} string, and if possible
\index{generated@\texttt{\textcurrency{GENERATED}\textcurrency}} have
a starting underscore (that is, a
\textcolor{blue}{\large\textbf{\texttt{\_}}} character) in their file
name.

{\textcolor{red}{\large @@TO BE COMPLETED}}

\section{Configuring \texttt{bismon} from its source code}
\label{sec:configure-bismon}

\textbf{\large Warning:} This configuration step has to be done again as soon
as your \href{http://gcc.gnu.org/}{GCC} compiler or cross-compiler has
changed versions, or when you have added new important libraries on
the \textsc{Linux} workstation running \emph{Bismon}.

First, \textbf{inspect, and \emph{improve if needed}, the \texttt{Configure} shell
script} for \texttt{/bin/bash}. \textbf{Then run that script} using the
\texttt{./Configure} command.
\index{configure@\texttt{Configure} script}
\index{configuration}

\section{Building \texttt{bismon} from its source code}
\label{sec:building-bismon}

\textbf{\large Warning:} This building step should probably be run
every evening, e.g. using a
\href{https://man7.org/linux/man-pages/man1/crontab.1.html}{\texttt{crontab}(1)}
job. It should be done only after the \texttt{./Configure} script has
been successfully run.

First, \textbf{inspect, and \emph{improve if needed}, the \texttt{Build} shell
script} for \texttt{/bin/bash}. \textbf{Then run that script} using the
\textcolor{\texttt{./Build}} command. 
\index{build@\texttt{Build} script}
\index{building!\texttt{bismon}}


\subsection{Checking the version of \texttt{bismon}}

Once the \texttt{./Build} script did work correctly, there should be
some \texttt{bismon} executable file. Check first using the
\texttt{file ./bismon} command, it should give you something similar
to:

\begin{verbatim}
./bismon: ELF 64-bit LSB shared object, x86-64, version 1 (SYSV), dynamically linked,
 interpreter /lib64/ld-linux-x86-64.so.2,
BuildID[sha1]=b4e74f225dff6115a01764abfe361a1b7757a208, for GNU/Linux 3.2.0,
with debug_info, not stripped
\end{verbatim}

Then use \texttt{ldd ./bismon} to verify that all dependencies are
present. On some computer, I am possibly getting the following output:

\begin{relsize}{-1}
\begin{verbatim}
 % ldd ./bismon
	linux-vdso.so.1 (0x00007ffee532a000)
	libonion.so.0 => /usr/local/lib/libonion.so.0 (0x00007f5ee9ec2000)
	libglib-2.0.so.0 => /lib/x86_64-linux-gnu/libglib-2.0.so.0 (0x00007f5ee9d99000)
	libjansson.so.4 => /usr/local/lib/libjansson.so.4 (0x00007f5ee9d8a000)
	libcrypt.so.1 => /lib/x86_64-linux-gnu/libcrypt.so.1 (0x00007f5ee9d4f000)
	libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x00007f5ee9d2c000)
	libdl.so.2 => /lib/x86_64-linux-gnu/libdl.so.2 (0x00007f5ee9d24000)
	libstdc++.so.6 => /lib/x86_64-linux-gnu/libstdc++.so.6 (0x00007f5ee9b43000)
	libm.so.6 => /lib/x86_64-linux-gnu/libm.so.6 (0x00007f5ee99f4000)
	libgcc_s.so.1 => /lib/x86_64-linux-gnu/libgcc_s.so.1 (0x00007f5ee99d9000)
	libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f5ee97e7000)
	libxml2.so.2 => /lib/x86_64-linux-gnu/libxml2.so.2 (0x00007f5ee962d000)
	libpam.so.0 => /lib/x86_64-linux-gnu/libpam.so.0 (0x00007f5ee961b000)
	libgcrypt.so.20 => /lib/x86_64-linux-gnu/libgcrypt.so.20 (0x00007f5ee94fb000)
	libgnutls.so.30 => /lib/x86_64-linux-gnu/libgnutls.so.30 (0x00007f5ee9325000)
	libsqlite3.so.0 => /lib/x86_64-linux-gnu/libsqlite3.so.0 (0x00007f5ee91fc000)
	libhiredis.so.0.14 => /lib/x86_64-linux-gnu/libhiredis.so.0.14 (0x00007f5ee91e9000)
	libsystemd.so.0 => /lib/x86_64-linux-gnu/libsystemd.so.0 (0x00007f5ee913a000)
	libpcre.so.3 => /lib/x86_64-linux-gnu/libpcre.so.3 (0x00007f5ee90c7000)
	/lib64/ld-linux-x86-64.so.2 (0x00007f5eea0b9000)
	libicuuc.so.66 => /lib/x86_64-linux-gnu/libicuuc.so.66 (0x00007f5ee8edf000)
	libz.so.1 => /lib/x86_64-linux-gnu/libz.so.1 (0x00007f5ee8ec3000)
	liblzma.so.5 => /lib/x86_64-linux-gnu/liblzma.so.5 (0x00007f5ee8e9a000)
	libaudit.so.1 => /lib/x86_64-linux-gnu/libaudit.so.1 (0x00007f5ee8e6e000)
	libgpg-error.so.0 => /lib/x86_64-linux-gnu/libgpg-error.so.0 (0x00007f5ee8e4b000)
	libp11-kit.so.0 => /lib/x86_64-linux-gnu/libp11-kit.so.0 (0x00007f5ee8d13000)
	libidn2.so.0 => /lib/x86_64-linux-gnu/libidn2.so.0 (0x00007f5ee8cf2000)
	libunistring.so.2 => /lib/x86_64-linux-gnu/libunistring.so.2 (0x00007f5ee8b70000)
	libtasn1.so.6 => /lib/x86_64-linux-gnu/libtasn1.so.6 (0x00007f5ee8b5a000)
	libnettle.so.7 => /lib/x86_64-linux-gnu/libnettle.so.7 (0x00007f5ee8b20000)
	libhogweed.so.5 => /lib/x86_64-linux-gnu/libhogweed.so.5 (0x00007f5ee8ae8000)
	libgmp.so.10 => /lib/x86_64-linux-gnu/libgmp.so.10 (0x00007f5ee8a62000)
	librt.so.1 => /lib/x86_64-linux-gnu/librt.so.1 (0x00007f5ee8a57000)
	liblz4.so.1 => /lib/x86_64-linux-gnu/liblz4.so.1 (0x00007f5ee8a36000)
	libicudata.so.66 => /lib/x86_64-linux-gnu/libicudata.so.66 (0x00007f5ee6f75000)
	libcap-ng.so.0 => /lib/x86_64-linux-gnu/libcap-ng.so.0 (0x00007f5ee6f6d000)
	libffi.so.7 => /lib/x86_64-linux-gnu/libffi.so.7 (0x00007f5ee6f5f000)
\end{verbatim}
\end{relsize}

At last, you can ask \texttt{bismon} to give its version information
using \texttt{./bismon --version} which might output something like:

\begin{relsize}{-1}
\begin{verbatim}
% ./bismon --version
./bismon: version information
	 timestamp: jeu. 28 janv. 2021 13:32:53
	 git id: d62d320623ad2a7e73019e736870039508c36d02
	 last git commit: d62d320623ad tell about the Build script in end of BISMON-config.cc
	 last git tag: heads/master
	 source checksum: d929d9edebcd6a76618901c7ebbaed71
	 source dir: /home/basile/bismon-master
	 GNUmakefile: /home/basile/bismon-master/GNUmakefile
########
run
	   ./bismon --help
to get help.
\end{verbatim}
\end{relsize}

Please report the output of \texttt{./bismon --version} before any question on \textsc{Bismon}.

The output of \texttt{./bismon --help} is giving up to date
information about invoking \texttt{./bismon} (e.g. in some
\texttt{cron} script). For example:

\begin{relsize}{-1.5}
\verbatiminput{generated/005-bismon-help.tex}
\end{relsize}

\section{Dumping and restoring the \texttt{bismon} persistent heap}
\label{sec:dumping-restoring-heap}

It is absolutely essential that the \texttt{make redump} command works
well., and you need to run that command regularily.
\index{redump@\texttt{redump} target for \texttt{make}} See also \S
\ref{subsec:persistence}

It is practically important to use the periodically
\href{http://git-scm.com/}{\texttt{git} version control} system on the
repository, and this includes the persistent heap dump files
\texttt{store*BISMON.bmon} - when \texttt{bismon} is \textbf{not
  running}. It is recommended to \texttt{git commit} these files twice
a day at least, when the \texttt{bismon} executable is not running.

\end{appendices}
