X-Git-Url: https://www.ginac.de/ginac.git//ginac.git?p=ginac.git;a=blobdiff_plain;f=doc%2Ftutorial%2Fginac.texi;h=8f10e13b8ed3bf6a80e53c52942974b7c74d7e96;hp=0c3646127305d19ef304254dc6ac9529265be0c6;hb=8ba901b532b844d49ffbd11f906f9124f357db1f;hpb=6c4ddbcabae766fc993d40de53cbbcdbd758d61d diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi index 0c364612..8f10e13b 100644 --- a/doc/tutorial/ginac.texi +++ b/doc/tutorial/ginac.texi @@ -23,7 +23,7 @@ This is a tutorial that documents GiNaC @value{VERSION}, an open framework for symbolic computation within the C++ programming language. -Copyright (C) 1999-2006 Johannes Gutenberg University Mainz, Germany +Copyright (C) 1999-2007 Johannes Gutenberg University Mainz, Germany Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -51,7 +51,7 @@ notice identical to this one. @page @vskip 0pt plus 1filll -Copyright @copyright{} 1999-2006 Johannes Gutenberg University Mainz, Germany +Copyright @copyright{} 1999-2007 Johannes Gutenberg University Mainz, Germany @sp 2 Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -134,7 +134,7 @@ the near future. @section License The GiNaC framework for symbolic computation within the C++ programming -language is Copyright @copyright{} 1999-2006 Johannes Gutenberg +language is Copyright @copyright{} 1999-2007 Johannes Gutenberg University Mainz, Germany. This program is free software; you can redistribute it and/or @@ -478,9 +478,10 @@ met. First of all, you need to have a C++-compiler adhering to the ANSI-standard @cite{ISO/IEC 14882:1998(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. Perl is needed by the built -process as well, since some of the source files are automatically -generated by Perl scripts. Last but not least, the CLN library +@file{/bin/sh}, GNU @command{bash} is fine. The pkg-config utility is +required for the configuration, it can be downloaded from +@uref{http://pkg-config.freedesktop.org}. +Last but not least, the CLN library is used extensively and needs to be installed on your system. Please get it from @uref{ftp://ftpthep.physik.uni-mainz.de/pub/gnu/} (it is covered by GPL) and install it prior to trying to install @@ -553,7 +554,7 @@ warning levels. If omitted, it defaults to @option{-g the file @file{configure.ac}. It is only distributed in packaged releases of GiNaC. If you got the naked sources, e.g. from CVS, you must generate @command{configure} along with the various -@file{Makefile.in} by using the @command{autogen.sh} script. This will +@file{Makefile.in} by using the @command{autoreconf} utility. This will require a fair amount of support from your local toolchain, though.} The whole process is illustrated in the following two @@ -7733,9 +7734,8 @@ The RTTI in GiNaC is based on two mechanisms: @item The @code{basic} class declares a member variable @code{tinfo_key} which -holds an unsigned integer that identifies the object's class. These numbers -are defined in the @file{tinfos.h} header file for the built-in GiNaC -classes. They all start with @code{TINFO_}. +holds a variable of @code{tinfo_t} type (which is actually just +@code{const void*}) that identifies the object's class. @item By means of some clever tricks with static members, GiNaC maintains a list @@ -7772,17 +7772,6 @@ using namespace std; using namespace GiNaC; @end example -The first thing we have to do is to define a @code{tinfo_key} for our new -class. This can be any arbitrary unsigned number that is not already taken -by one of the existing classes but it's better to come up with something -that is unlikely to clash with keys that might be added in the future. The -numbers in @file{tinfos.h} are modeled somewhat after the class hierarchy -which is not a requirement but we are going to stick with this scheme: - -@example -const unsigned TINFO_mystring = 0x42420001U; -@end example - Now we can write down the class declaration. The class stores a C++ @code{string} and the user shall be able to construct a @code{mystring} object from a C or C++ string: @@ -7866,11 +7855,14 @@ which are the two constructors we declared. Let's proceed step-by-step. The default constructor looks like this: @example -mystring::mystring() : inherited(TINFO_mystring) @{@} +mystring::mystring() : inherited(&mystring::tinfo_static) @{@} @end example The golden rule is that in all constructors you have to set the -@code{tinfo_key} member to the @code{TINFO_*} value of your class. Otherwise +@code{tinfo_key} member to the @code{&your_class_name::tinfo_static} +@footnote{Each GiNaC class has a static member called tinfo_static. +This member is declared by the GINAC_DECLARE_REGISTERED_CLASS macros +and defined by the GINAC_IMPLEMENT_REGISTERED_CLASS macros.}. Otherwise it will be set by the constructor of the superclass and all hell will break loose in the RTTI. For your convenience, the @code{basic} class provides a constructor that takes a @code{tinfo_key} value, which we are using here @@ -7960,8 +7952,8 @@ all relevant member variables. Now the only thing missing is our two new constructors: @example -mystring::mystring(const string &s) : inherited(TINFO_mystring), str(s) @{@} -mystring::mystring(const char *s) : inherited(TINFO_mystring), str(s) @{@} +mystring::mystring(const string &s) : inherited(&mystring::tinfo_static), str(s) @{@} +mystring::mystring(const char *s) : inherited(&mystring::tinfo_static), str(s) @{@} @end example No surprises here. We set the @code{str} member from the argument and @@ -8100,7 +8092,7 @@ public: ex mystring::eval(int level) const @{ string new_str; - for (int i=0; i= 'A' && c <= 'Z') new_str += tolower(c); @@ -8198,6 +8190,28 @@ should become a need. That's it. May the source be with you! +@subsection Upgrading extension classes from older version of GiNaC + +If you got some extension classes for GiNaC 1.3.X some changes are +necessary in order to make your code work with GiNaC 1.4. + +@itemize @bullet +@item constructors which set @code{tinfo_key} such as + +@example +myclass::myclass() : inherited(TINFO_myclass) @{@} +@end example + +need to be rewritten as + +@example +myclass::myclass() : inherited(&myclass::tinfo_static) @{@} +@end example + +@item TINO_myclass is not necessary any more and can be removed. + +@end itemize + @node A comparison with other CAS, Advantages, Adding classes, Top @c node-name, next, previous, up @@ -8513,78 +8527,38 @@ expansion and the like are reimplemented for @code{add} and @code{mul}, but the data structure is inherited from @code{expairseq}. -@node Package tools, ginac-config, Internal representation of products and sums, Top +@node Package tools, Configure script options, Internal representation of products and sums, Top @c node-name, next, previous, up @appendix Package tools 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. GiNaC includes two tools to make this process easier. - -@menu -* ginac-config:: A shell script to detect compiler and linker flags. -* AM_PATH_GINAC:: Macro for GNU automake. -@end menu - - -@node ginac-config, AM_PATH_GINAC, Package tools, Package tools -@c node-name, next, previous, up -@section @command{ginac-config} -@cindex ginac-config - -@command{ginac-config} is a shell script that you can use to determine -the compiler and linker command line options required to compile and -link a program with the GiNaC library. - -@command{ginac-config} takes the following flags: - -@table @samp -@item --version -Prints out the version of GiNaC installed. -@item --cppflags -Prints '-I' flags pointing to the installed header files. -@item --libs -Prints out the linker flags necessary to link a program against GiNaC. -@item --prefix[=@var{PREFIX}] -If @var{PREFIX} is specified, overrides the configured value of @env{$prefix}. -(And of exec-prefix, unless @code{--exec-prefix} is also specified) -Otherwise, prints out the configured value of @env{$prefix}. -@item --exec-prefix[=@var{PREFIX}] -If @var{PREFIX} is specified, overrides the configured value of @env{$exec_prefix}. -Otherwise, prints out the configured value of @env{$exec_prefix}. -@end table - -Typically, @command{ginac-config} will be used within a configure -script, as described below. It, however, can also be used directly from -the command line using backquotes to compile a simple program. For -example: - +setting the correct command line options for the compiler and linker can +be difficult. The @command{pkg-config} 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 +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.} @example -c++ -o simple `ginac-config --cppflags` simple.cpp `ginac-config --libs` +g++ -o simple `pkg-config --cflags --libs ginac` simple.cpp @end example This command line might expand to (for example): - @example -cc -o simple -I/usr/local/include simple.cpp -L/usr/local/lib \ - -lginac -lcln -lstdc++ +g++ -o simple -lginac -lcln simple.cpp @end example -Not only is the form using @command{ginac-config} easier to type, it will +Not only is the form using @command{pkg-config} easier to type, it will work on any system, no matter how GiNaC was configured. - -@node AM_PATH_GINAC, Configure script options, ginac-config, Package tools -@c node-name, next, previous, up -@section @samp{AM_PATH_GINAC} -@cindex AM_PATH_GINAC - -For packages configured using GNU automake, GiNaC also provides -a macro to automate the process of checking for GiNaC. +For packages configured using GNU automake, @command{pkg-config} also +provides the @code{PKG_CHECK_MODULES} macro to automate the process of +checking for libraries @example -AM_PATH_GINAC([@var{MINIMUM-VERSION}, [@var{ACTION-IF-FOUND} - [, @var{ACTION-IF-NOT-FOUND}]]]) +PKG_CHECK_MODULES(MYAPP, ginac >= MINIMUM_VERSION, + [@var{ACTION-IF-FOUND}], + [@var{ACTION-IF-NOT-FOUND}]) @end example This macro: @@ -8592,113 +8566,91 @@ This macro: @itemize @bullet @item -Determines the location of GiNaC using @command{ginac-config}, which is -either found in the user's path, or from the environment variable -@env{GINACLIB_CONFIG}. +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 +the environment variable @env{PKG_CONFIG_PATH}. @item Tests the installed libraries to make sure that their version -is later than @var{MINIMUM-VERSION}. (A default version will be used -if not specified) +is later than @var{MINIMUM-VERSION}. @item -If the required version was found, sets the @env{GINACLIB_CPPFLAGS} variable -to the output of @command{ginac-config --cppflags} and the @env{GINACLIB_LIBS} -variable to the output of @command{ginac-config --libs}, and calls +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 @samp{AC_SUBST()} for these variables so they can be used in generated makefiles, and then executes @var{ACTION-IF-FOUND}. @item -If the required version was not found, sets @env{GINACLIB_CPPFLAGS} and -@env{GINACLIB_LIBS} to empty strings, and executes @var{ACTION-IF-NOT-FOUND}. +If the required version was not found, executes @var{ACTION-IF-NOT-FOUND}. @end itemize -This macro is in file @file{ginac.m4} which is installed in -@file{$datadir/aclocal}. Note that if automake was installed with a -different @samp{--prefix} than GiNaC, you will either have to manually -move @file{ginac.m4} to automake's @file{$datadir/aclocal}, or give -aclocal the @samp{-I} option when running it. - @menu -* Configure script options:: Configuring a package that uses AM_PATH_GINAC. -* Example package:: Example of a package using AM_PATH_GINAC. +* Configure script options:: Configuring a package that uses GiNaC +* Example package:: Example of a package using GiNaC @end menu -@node Configure script options, Example package, AM_PATH_GINAC, AM_PATH_GINAC +@node Configure script options, Example package, Package tools, Package tools @c node-name, next, previous, up -@subsection Configuring a package that uses @samp{AM_PATH_GINAC} - -Simply make sure that @command{ginac-config} is in your path, and run -the configure script. - -Notes: +@subsection Configuring a package that uses GiNaC -@itemize @bullet - -@item The directory where the GiNaC libraries are installed needs -to be found by your system's dynamic linker. - -This is generally done by +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*}. -@display -editing @file{/etc/ld.so.conf} and running @command{ldconfig} -@end display +The short summary below describes how to do this on a GNU/Linux +system. -or by - -@display -setting the environment variable @env{LD_LIBRARY_PATH}, -@end display - -or, as a last resort, - -@display -giving a @samp{-R} or @samp{-rpath} flag (depending on your linker) when -running configure, for instance: +Suppose GiNaC is installed into the directory @samp{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 -LDFLAGS=-R/home/cbauer/lib ./configure +# echo PREFIX/lib >> /etc/ld.so.conf +# ldconfig @end example -@end display @item -You can also specify a @command{ginac-config} not in your path by -setting the @env{GINACLIB_CONFIG} environment variable to the -name of the executable +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 +@end example @item -If you move the GiNaC package from its installed location, -you will either need to modify @command{ginac-config} script -manually to point to the new location or rebuild GiNaC. +or give a @samp{-L} and @samp{--rpath} flags when running configure, +for instance: +@example +$ LDFLAGS='-Wl,-LPREFIX/lib -Wl,--rpath=PREFIX/lib' ./configure +@end example @end itemize -Advanced note: - -@itemize @bullet -@item -configure flags - +To tell @command{pkg-config} where the @file{ginac.pc} file is, +set the @env{PKG_CONFIG_PATH} environment variable: @example ---with-ginac-prefix=@var{PREFIX} ---with-ginac-exec-prefix=@var{PREFIX} +$ export PKG_CONFIG_PATH=PREFIX/lib/pkgconfig @end example -are provided to override the prefix and exec-prefix that were stored -in the @command{ginac-config} shell script by GiNaC's configure. You are -generally better off configuring GiNaC with the right path to begin with. -@end itemize +Finally, run the @command{configure} script +@example +$ ./configure +@end example +@c There are many other ways to do the same, @xref{Options, ,Command Line Options, ld, GNU ld manual}. -@node Example package, Bibliography, Configure script options, AM_PATH_GINAC +@node Example package, Bibliography, Configure script options, Package tools @c node-name, next, previous, up -@subsection Example of a package using @samp{AM_PATH_GINAC} +@subsection Example of a package using GiNaC The following shows how to build a simple package using automake -and the @samp{AM_PATH_GINAC} macro. The program used here is @file{simple.cpp}: +and the @samp{PKG_CHECK_MODULES} macro. The program used here is @file{simple.cpp}: @example #include @@ -8717,33 +8669,39 @@ int main() You should first read the introductory portions of the automake Manual, if you are not already familiar with it. -Two files are needed, @file{configure.in}, which is used to build the +Two files are needed, @file{configure.ac}, which is used to build the configure script: @example -dnl Process this file with autoconf to produce a configure script. -AC_INIT(simple.cpp) -AM_INIT_AUTOMAKE(simple.cpp, 1.0.0) +dnl Process this file with autoreconf to produce a configure script. +AC_INIT([simple], 1.0.0, bogus@@example.net) +AC_CONFIG_SRCDIR(simple.cpp) +AM_INIT_AUTOMAKE([foreign 1.8]) AC_PROG_CXX AC_PROG_INSTALL -AC_LANG_CPLUSPLUS +AC_LANG([C++]) -AM_PATH_GINAC(0.9.0, [ - LIBS="$LIBS $GINACLIB_LIBS" - CPPFLAGS="$CPPFLAGS $GINACLIB_CPPFLAGS" -], AC_MSG_ERROR([need to have GiNaC installed])) +PKG_CHECK_MODULES(SIMPLE, ginac >= 1.3.7) AC_OUTPUT(Makefile) @end example -The only command in this which is not standard for automake -is the @samp{AM_PATH_GINAC} macro. +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} +and @var{SIMPLE_LIBS}. Otherwise, it dies with the error message like +@example +configure: error: Package requirements (ginac >= 1.3.7) were not met: -That command does the following: If a GiNaC version greater or equal -than 0.7.0 is found, then it adds @env{$GINACLIB_LIBS} to @env{$LIBS} -and @env{$GINACLIB_CPPFLAGS} to @env{$CPPFLAGS}. Otherwise, it dies with -the error message `need to have GiNaC installed' +Requested 'ginac >= 1.3.7' but version of GiNaC is 1.3.5 + +Consider adjusting the PKG_CONFIG_PATH environment variable if you +installed software in a non-standard prefix. + +Alternatively, you may set the environment variables SIMPLE_CFLAGS +and SIMPLE_LIBS to avoid the need to call pkg-config. +See the pkg-config man page for more details. +@end example And the @file{Makefile.am}, which will be used to build the Makefile. @@ -8751,31 +8709,24 @@ And the @file{Makefile.am}, which will be used to build the Makefile. ## Process this file with automake to produce Makefile.in bin_PROGRAMS = simple simple_SOURCES = simple.cpp +simple_CPPFLAGS = $(SIMPLE_CFLAGS) +simple_LDADD = $(SIMPLE_LIBS) @end example This @file{Makefile.am}, says that we are building a single executable, from a single source file @file{simple.cpp}. Since every program -we are building uses GiNaC we simply added the GiNaC options -to @env{$LIBS} and @env{$CPPFLAGS}, but in other circumstances, we might -want to specify them on a per-program basis: for instance by -adding the lines: - -@example -simple_LDADD = $(GINACLIB_LIBS) -INCLUDES = $(GINACLIB_CPPFLAGS) -@end example - -to the @file{Makefile.am}. +we are building uses GiNaC we could have simply added @var{SIMPLE_CFLAGS} +to @var{CPPFLAGS} and @var{SIMPLE_LIBS} to @var{LIBS}. However, it is +more flexible to specify libraries and complier options on a per-program +basis. To try this example out, create a new directory and add the three files above to it. -Now execute the following commands: +Now execute the following command: @example -$ automake --add-missing -$ aclocal -$ autoconf +$ autoreconf -i @end example You now have a package that can be built in the normal fashion