From 110534c3ee2fc56c354e73bc484dc9ce38fb64bc Mon Sep 17 00:00:00 2001 From: Richard Kreckel Date: Thu, 2 Jan 2025 18:32:17 +0100 Subject: [PATCH] [DOC] Modernize documentation about required infrastructure. --- INSTALL | 37 ++++---------- doc/tutorial/ginac.texi | 108 ++++++++++++++++------------------------ 2 files changed, 54 insertions(+), 91 deletions(-) diff --git a/INSTALL b/INSTALL index 07e7cf42..08266ee8 100644 --- a/INSTALL +++ b/INSTALL @@ -4,26 +4,16 @@ PREREQUISITES GiNaC requires the CLN library by Bruno Haible installed on your system. It is available from . -You will also need a decent ISO C++-11 compiler. We recommend the C++ -compiler from the GNU compiler collection, GCC >= 4.8. If you have a -different or older compiler you are on your own. Note that you may have to -use the same compiler you compiled CLN with because of differing -name-mangling schemes. +You will also need a decent C++ compiler (ISO C++-11 or higher). We recommend +the C++ compiler from the GNU compiler collection or the one from the LLVM +project. If you have a different compiler, you are on your own. Note that you +may have to use the same compiler you compiled CLN with for compatibility. -The pkg-config utility is required for configuration, it can be downloaded -from . Also, Python 3 is required. +The pkgconf utility is required for configuration: . +Alternatively, pkg-config works as well. -To build the GiNaC tutorial and reference manual the doxygen utility -(it can be downloaded from https://www.doxygen.nl/) and TeX are necessary. - -Known to work with: - - Linux on x86 and x86_64 using - - GCC 4.8, 4.9, 5.x, 6.x, 7.x, 8.x, and 9.x - - Clang 3.5, 3.6, 3.7, 3.8, 6.x, 7.x, 8.x, and 9.x - -Known not to work with: - - Clang 2.7 and earlier due to poor C++ support. - - GCC < 4.6.0 due to missing C++-11 support +To build the GiNaC tutorial and reference manual, the doxygen utility +(it can be downloaded from ) and TeX are necessary. If you install from git, you also need GNU autoconf (>=2.59), automake (>=1.8), libtool (>= 1.5), python (version 2.7 or 3.x), bison (>= 2.3), flex (>= 2.5.33) @@ -53,8 +43,8 @@ library works correctly you can use $ make check -The "configure" script can be given a number of options to enable and -disable various features. For a complete list, type: +The "configure" script can be given a number of options to enable and disable +various features. For a complete list, type: $ ./configure --help @@ -129,10 +119,3 @@ libreadline and libreadline-dev (or readline-devel). If your system's vendor doesn't supply such packages, go to and compile it yourself. Note that non-GNU versions of libreadline (in particular one shipped with Mac OS X) are not supported at the moment. - -Problems with missing standard header files -------------------------------------------- - -Building GiNaC requires many standard header files. If you get a configure -error complaining about such missing files your compiler and library are -probably not up to date enough and it's no worth continuing. diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi index dc3a0114..33e9abba 100644 --- a/doc/tutorial/ginac.texi +++ b/doc/tutorial/ginac.texi @@ -481,10 +481,9 @@ met. First of all, you need to have a C++-compiler adhering to the ISO standard @cite{ISO/IEC 14882:2011(E)}. We used GCC for development so if you have a different compiler you are on your own. For the configuration to succeed you need a Posix compliant shell installed in -@file{/bin/sh}, GNU @command{bash} is fine. The pkg-config utility is +@file{/bin/sh}, GNU @command{bash} is fine. The @command{pkgconf} utility is required for the configuration, it can be downloaded from -@uref{http://pkg-config.freedesktop.org}. -Last but not least, the CLN library +@uref{http://pkgconf.org/}. Last but not least, the CLN library is used extensively and needs to be installed on your system. Please get it from @uref{https://www.ginac.de/CLN/} (it is licensed under the GPL) and install it prior to trying to install GiNaC. The configure @@ -548,8 +547,8 @@ want to have the documentation installed in some other directory than In addition, you may specify some environment variables. @env{CXX} holds the path and the name of the C++ compiler in case you want to override the default in your path. (The @command{configure} script -searches your path for @command{c++}, @command{g++}, @command{gcc}, -@command{CC}, @command{cxx} and @command{cc++} in that order.) It may +searches your path for @command{c++}, @command{g++}, @command{aCC}, +@command{cxx}, @command{cc++}, @command{clang++}, in that order.) It may be very useful to define some compiler flags with the @env{CXXFLAGS} environment variable, like optimization, debugging information and warning levels. If omitted, it defaults to @option{-g @@ -660,7 +659,7 @@ if they don't already exist): @item @file{libginac.a} will go into @file{@var{PREFIX}/lib/} (or -@file{@var{LIBDIR}}) which defaults to @file{/usr/local/lib/}. +@file{@var{LIBDIR}} if specified) which defaults to @file{/usr/local/lib/}. So will @file{libginac.so} unless the configure script was given the option @option{--disable-shared}. The proper symlinks will be established as well. @@ -1725,8 +1724,9 @@ the C++ standard library: @example ... - // print the elements of the list (requires #include ) - std::copy(l.begin(), l.end(), ostream_iterator(cout, "\n")); + // print the elements of the list using ranged-based for loop + for (auto i: l) + cout << i << endl; // sum up the elements of the list (requires #include ) ex sum = std::accumulate(l.begin(), l.end(), ex(0)); @@ -6800,7 +6800,7 @@ will be installed together with GiNaC in the configured @code{$LIBEXECDIR} export additional compiler flags via the @env{$CXXFLAGS} variable: @example -setenv("CXXFLAGS", "-O3 -fomit-frame-pointer -ffast-math", 1); +setenv("CXXFLAGS", "-O3 -fomit-frame-pointer", 1); compile_ex(...); @end example @@ -8565,34 +8565,11 @@ speed with other CAS. @c node-name, next, previous, up @section Disadvantages -Of course it also has some disadvantages: - -@itemize @bullet - -@item -advanced features: GiNaC cannot compete with a program like -@emph{Reduce} which exists for more than 30 years now or @emph{Maple} -which grows since 1981 by the work of dozens of programmers, with -respect to mathematical features. Integration, -non-trivial simplifications, limits etc. are missing in GiNaC (and are -not planned for the near future). - -@item -portability: While the GiNaC library itself is designed to avoid any -platform dependent features (it should compile on any ANSI compliant C++ -compiler), the currently used version of the CLN library (fast large -integer and arbitrary precision arithmetics) can only by compiled -without hassle on systems with the C++ compiler from the GNU Compiler -Collection (GCC).@footnote{This is because CLN uses PROVIDE/REQUIRE like -macros to let the compiler gather all static initializations, which -works for GNU C++ only. Feel free to contact the authors in case you -really believe that you need to use a different compiler. We have -occasionally used other compilers and may be able to give you advice.} -GiNaC uses recent language features like explicit constructors, mutable -members, RTTI, @code{dynamic_cast}s and STL, so ANSI compliance is meant -literally. - -@end itemize +GiNaC cannot compete with a program like @emph{Reduce} or @emph{Maple} +which exists for more than 50 years now with respect to some +mathematical features. Integration, non-trivial simplifications, +limits etc. are missing in GiNaC (and are not planned for the near +future). @node Why C++?, Internal structures, Disadvantages, A comparison with other CAS @@ -8797,16 +8774,17 @@ but the data structure is inherited from @code{expairseq}. @c node-name, next, previous, up @appendix Package tools +@cindex @command{pkgconf} If you are creating a software package that uses the GiNaC library, setting the correct command line options for the compiler and linker can -be difficult. The @command{pkg-config} utility makes this process +be difficult. The @command{pkgconf} utility makes this process easier. GiNaC supplies all necessary data in @file{ginac.pc} (installed -into @code{/usr/local/lib/pkgconfig} by default). To compile a simple +into @code{@var{LIBDIR}/pkgconfig} by default). To compile a simple program use @footnote{If GiNaC is installed into some non-standard directory @var{prefix} one should set the @var{PKG_CONFIG_PATH} -environment variable to @var{prefix}/lib/pkgconfig for this to work.} +environment variable to @code{@var{LIBDIR}/pkgconfig} for this to work.} @example -g++ -o simple simple.cpp `pkg-config --cflags --libs ginac` +g++ -o simple simple.cpp `pkgconf --cflags --libs ginac` @end example This command line might expand to (for example): @@ -8814,15 +8792,15 @@ This command line might expand to (for example): g++ -o simple simple.cpp -lginac -lcln @end example -Not only is the form using @command{pkg-config} easier to type, it will +Not only is the form using @command{pkgconf} easier to type, it will work on any system, no matter how GiNaC was configured. -For packages configured using GNU automake, @command{pkg-config} also +For packages configured using GNU automake, @command{pkgconf} also provides the @code{PKG_CHECK_MODULES} macro to automate the process of checking for libraries @example -PKG_CHECK_MODULES(MYAPP, ginac >= MINIMUM_VERSION, +PKG_CHECK_MODULES(MYAPP, ginac >= @var{MINIMUM_VERSION}, [@var{ACTION-IF-FOUND}], [@var{ACTION-IF-NOT-FOUND}]) @end example @@ -8833,7 +8811,7 @@ This macro: @item Determines the location of GiNaC using data from @file{ginac.pc}, which is -either found in the default @command{pkg-config} search path, or from +either found in the default @command{pkgconf} search path, or from the environment variable @env{PKG_CONFIG_PATH}. @item @@ -8842,8 +8820,8 @@ is later than @var{MINIMUM-VERSION}. @item If the required version was found, sets the @env{MYAPP_CFLAGS} variable -to the output of @command{pkg-config --cflags ginac} and the @env{MYAPP_LIBS} -variable to the output of @command{pkg-config --libs ginac}, and calls +to the output of @command{pkgconf --cflags ginac} and the @env{MYAPP_LIBS} +variable to the output of @command{pkgconf --libs ginac}, and calls @samp{AC_SUBST()} for these variables so they can be used in generated makefiles, and then executes @var{ACTION-IF-FOUND}. @@ -8865,28 +8843,28 @@ If the required version was not found, executes @var{ACTION-IF-NOT-FOUND}. The directory where the GiNaC libraries are installed needs to be found by your system's dynamic linkers (both compile- and run-time ones). See the documentation of your system linker for details. Also -make sure that @file{ginac.pc} is in @command{pkg-config}'s search path, -@xref{pkg-config, ,pkg-config, *manpages*}. +make sure that @file{ginac.pc} is in @command{pkgconf}'s search path, +@xref{pkgconf, ,pkgconf, *manpages*}. The short summary below describes how to do this on a GNU/Linux system. -Suppose GiNaC is installed into the directory @samp{PREFIX}. To tell +Suppose GiNaC is installed into the directory @var{PREFIX}. To tell the linkers where to find the library one should @itemize @bullet @item edit @file{/etc/ld.so.conf} and run @command{ldconfig}. For example, @example -# echo PREFIX/lib >> /etc/ld.so.conf +# echo @var{PREFIX}/lib >> /etc/ld.so.conf # ldconfig @end example @item or set the environment variables @env{LD_LIBRARY_PATH} and @env{LD_RUN_PATH} @example -$ export LD_LIBRARY_PATH=PREFIX/lib -$ export LD_RUN_PATH=PREFIX/lib +$ export LD_LIBRARY_PATH=@var{PREFIX}/lib +$ export LD_RUN_PATH=@var{PREFIX}/lib @end example @item @@ -8894,14 +8872,14 @@ or give a @samp{-L} and @samp{--rpath} flags when running configure, for instance: @example -$ LDFLAGS='-Wl,-LPREFIX/lib -Wl,--rpath=PREFIX/lib' ./configure +$ LDFLAGS='-Wl,-L@var{PREFIX}/lib -Wl,--rpath=@var{PREFIX}/lib' ./configure @end example @end itemize -To tell @command{pkg-config} where the @file{ginac.pc} file is, +To tell @command{pkgconf} where the @file{ginac.pc} file is, set the @env{PKG_CONFIG_PATH} environment variable: @example -$ export PKG_CONFIG_PATH=PREFIX/lib/pkgconfig +$ export PKG_CONFIG_PATH=@var{PREFIX}/lib/pkgconfig @end example Finally, run the @command{configure} script @@ -8933,33 +8911,35 @@ int main() @end example You should first read the introductory portions of the automake -Manual, if you are not already familiar with it. +manual, if you are not already familiar with it. Two files are needed, @file{configure.ac}, which is used to build the configure script: @example dnl Process this file with autoreconf to produce a configure script. -AC_INIT([simple], 1.0.0, bogus@@example.net) +AC_INIT([simple], [1.0.0], [simple@@example.net]) AC_CONFIG_SRCDIR(simple.cpp) -AM_INIT_AUTOMAKE([foreign 1.8]) +AM_INIT_AUTOMAKE AC_PROG_CXX AC_PROG_INSTALL AC_LANG([C++]) -PKG_CHECK_MODULES(SIMPLE, ginac >= 1.3.7) +PKG_CHECK_MODULES(SIMPLE, ginac >= 1.8.0) -AC_OUTPUT(Makefile) +AC_CONFIG_FILES([Makefile]) +AC_OUTPUT @end example The @samp{PKG_CHECK_MODULES} macro does the following: If a GiNaC version -greater or equal than 1.3.7 is found, then it defines @var{SIMPLE_CFLAGS} +greater or equal than 1.8.0 is found, then it defines @var{SIMPLE_CFLAGS} and @var{SIMPLE_LIBS}. Otherwise, it dies with the error message like @example -configure: error: Package requirements (ginac >= 1.3.7) were not met: +configure: error: Package requirements (ginac >= 1.8.0) were not met: -Requested 'ginac >= 1.3.7' but version of GiNaC is 1.3.5 +Package dependency requirement 'ginac >= 1.8.0' could not be satisfied. +Package 'ginac' has version '1.7.7', required version is '>= 1.8.0' Consider adjusting the PKG_CONFIG_PATH environment variable if you installed software in a non-standard prefix. -- 2.49.0