@include version.texi
+@dircategory Mathematics
@direntry
* ginac: (ginac). C++ library for symbolic computation.
@end direntry
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-2010 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
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1999-2006 Johannes Gutenberg University Mainz, Germany
+Copyright @copyright{} 1999-2010 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
@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-2010 Johannes Gutenberg
University Mainz, Germany.
This program is free software; you can redistribute it and/or
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
warning levels. If omitted, it defaults to @option{-g
-O2}.@footnote{The @command{configure} script is itself generated from
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
+releases of GiNaC. If you got the naked sources, e.g. from git, 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
have a look at the most important classes in the class hierarchy and
some of the relations among the classes:
+@ifnotinfo
@image{classhierarchy}
+@end ifnotinfo
+@ifinfo
+<PICTURE MISSING>
+@end ifinfo
The abstract classes shown here (the ones without drop-shadow) are of no
interest for the user. They are used internally in order to avoid code
Now, here is one important property of GiNaC that differentiates it from
other computer algebra programs you may have used: GiNaC does @emph{not} use
the names of symbols to tell them apart, but a (hidden) serial number that
-is unique for each newly created @code{symbol} object. In you want to use
+is unique for each newly created @code{symbol} object. If you want to use
one and the same symbol in different places in your program, you must only
create one @code{symbol} object and pass that around. If you create another
symbol, even if it has the same name, GiNaC will treat it as a different
@cindex @code{possymbol()}
Furthermore, it is also possible to declare a symbol as positive. This will,
for instance, enable the automatic simplification of @code{abs(x)} into
-@code{x}. This is done by declaying the symbol as @code{possymbol x("x");}.
+@code{x}. This is done by declaring the symbol as @code{possymbol x("x");}.
@node Numbers, Constants, Symbols, Basic concepts
@end example
Note that the variable @code{answer} is constructed here as an integer
-by @code{numeric}'s copy constructor but in an intermediate step it
+by @code{numeric}'s copy constructor, but in an intermediate step it
holds a rational number represented as integer numerator and integer
denominator. When multiplied by 10, the denominator becomes unity and
the result is automatically converted to a pure integer again.
@tab @dots{}equal to zero
@item @code{.is_positive()}
@tab @dots{}not complex and greater than 0
+@item @code{.is_negative()}
+@tab @dots{}not complex and smaller than 0
@item @code{.is_integer()}
@tab @dots{}a (non-complex) integer
@item @code{.is_pos_integer()}
@end multitable
@end cartouche
+@page
+
@subsection Numeric functions
The following functions can be applied to @code{numeric} objects and will be
@tab modulus in positive representation (in the range @code{[0, abs(b)-1]} with the sign of b, or zero)
@cindex @code{mod()}
@item @code{smod(a, b)}
-@tab modulus in symmetric representation (in the range @code{[-iquo(abs(b)-1, 2), iquo(abs(b), 2)]})
+@tab modulus in symmetric representation (in the range @code{[-iquo(abs(b), 2), iquo(abs(b), 2)]})
@cindex @code{smod()}
@item @code{irem(a, b)}
@tab integer remainder (has the sign of @math{a}, or is zero)
The predefined known constants are:
@cartouche
-@multitable @columnfractions .14 .30 .56
+@multitable @columnfractions .14 .32 .54
@item @strong{Name} @tab @strong{Common Name} @tab @strong{Numerical Value (to 35 digits)}
@item @code{Pi}
@tab Archimedes' constant
evaluation, is also available as
@example
ex adaptivesimpson(const ex & x, const ex & a, const ex & b, const ex & f,
-const ex & error)
+ const ex & error)
@end example
This function will throw an exception if the maximum depth is exceeded. The
last parameter of the function is optional and defaults to the
anything useful with it.
@cindex @code{get_value()}
-@cindex @code{get_dimension()}
+@cindex @code{get_dim()}
The methods
@example
ex idx::get_value();
-ex idx::get_dimension();
+ex idx::get_dim();
@end example
return the value and dimension of an @code{idx} object. If you have an index
that performs some more expensive operations:
-@itemize
+@itemize @bullet
@item it checks the consistency of free indices in sums in the same way
@code{get_free_indices()} does
@item it tries to give dummy indices that appear in different terms of a sum
obtained with the two member functions
@example
-unsigned ex::return_type() const;
-unsigned ex::return_type_tinfo() const;
+unsigned ex::return_type() const;
+return_type_t ex::return_type_tinfo() const;
@end example
The @code{return_type()} function returns one of three values (defined in
the header file @file{flags.h}), corresponding to three categories of
expressions in GiNaC:
-@itemize
+@itemize @bullet
@item @code{return_types::commutative}: Commutates with everything. Most GiNaC
classes are of this kind.
@item @code{return_types::noncommutative}: Non-commutative, belonging to a
@code{noncommutative_composite} expressions.
@end itemize
-The value returned by the @code{return_type_tinfo()} method is valid only
-when the return type of the expression is @code{noncommutative}. It is a
-value that is unique to the class of the object and usually one of the
-constants in @file{tinfos.h}, or derived therefrom.
+The @code{return_type_tinfo()} method returns an object of type
+@code{return_type_t} that contains information about the type of the expression
+and, if given, its representation label (see section on dirac gamma matrices for
+more details). The objects of type @code{return_type_t} can be tested for
+equality to test whether two expressions belong to the same category and
+therefore may not commute.
Here are a couple of examples:
@cartouche
-@multitable @columnfractions 0.33 0.33 0.34
-@item @strong{Expression} @tab @strong{@code{return_type()}} @tab @strong{@code{return_type_tinfo()}}
-@item @code{42} @tab @code{commutative} @tab -
-@item @code{2*x-y} @tab @code{commutative} @tab -
-@item @code{dirac_ONE()} @tab @code{noncommutative} @tab @code{TINFO_clifford}
-@item @code{dirac_gamma(mu)*dirac_gamma(nu)} @tab @code{noncommutative} @tab @code{TINFO_clifford}
-@item @code{2*color_T(a)} @tab @code{noncommutative} @tab @code{TINFO_color}
-@item @code{dirac_ONE()*color_T(a)} @tab @code{noncommutative_composite} @tab -
+@multitable @columnfractions .6 .4
+@item @strong{Expression} @tab @strong{@code{return_type()}}
+@item @code{42} @tab @code{commutative}
+@item @code{2*x-y} @tab @code{commutative}
+@item @code{dirac_ONE()} @tab @code{noncommutative}
+@item @code{dirac_gamma(mu)*dirac_gamma(nu)} @tab @code{noncommutative}
+@item @code{2*color_T(a)} @tab @code{noncommutative}
+@item @code{dirac_ONE()*color_T(a)} @tab @code{noncommutative_composite}
@end multitable
@end cartouche
-Note: the @code{return_type_tinfo()} of Clifford objects is only equal to
-@code{TINFO_clifford} for objects with a representation label of zero.
-Other representation labels yield a different @code{return_type_tinfo()},
-but it's the same for any two objects with the same label. This is also true
-for color objects.
-
A last note: With the exception of matrices, positive integer powers of
non-commutative objects are automatically expanded in GiNaC. For example,
@code{pow(a*b, 2)} becomes @samp{a*b*a*b} if @samp{a} and @samp{b} are
functional is not cyclic in
@tex $D \ne 4$
@end tex
+@ifnottex
+@math{D != 4}
+@end ifnottex
dimensions when acting on
expressions containing @samp{gamma5}, so it's not a proper trace. This
-@samp{gamma5} scheme is described in greater detail in
-@cite{The Role of gamma5 in Dimensional Regularization}.
+@samp{gamma5} scheme is described in greater detail in the article
+@cite{The Role of gamma5 in Dimensional Regularization} (@ref{Bibliography}).
The value of the trace itself is also usually different in 4 and in
@tex $D \ne 4$
@end tex
+@ifnottex
+@math{D != 4}
+@end ifnottex
dimensions:
@example
@subsubsection A generic Clifford algebra
A generic Clifford algebra, i.e. a
-@tex
-$2^n$
+@tex $2^n$
@end tex
+@ifnottex
+2^n
+@end ifnottex
dimensional algebra with
generators
@tex $e_k$
@end tex
+@ifnottex
+e_k
+@end ifnottex
satisfying the identities
@tex
-$e_i e_j + e_j e_i = M(i, j) + M(j, i) $
+$e_i e_j + e_j e_i = M(i, j) + M(j, i)$
@end tex
@ifnottex
e~i e~j + e~j e~i = M(i, j) + M(j, i)
with @samp{e.k}
directly supplied in the second form of the procedure. In the first form
the Clifford unit @samp{e.k} is generated by the call of
-@code{clifford_unit(mu, metr, rl)}. The previous code may be rewritten
-with the help of @code{lst_to_clifford()} as follows
+@code{clifford_unit(mu, metr, rl)}.
+@cindex pseudo-vector
+If the number of components supplied
+by @code{v} exceeds the dimensionality of the Clifford unit @code{e} by
+1 then function @code{lst_to_clifford()} uses the following
+pseudo-vector representation:
+@tex
+$v^0 {\bf 1} + v^1 e_0 + v^2 e_1 + ... + v^{n+1} e_n$
+@end tex
+@ifnottex
+@samp{v~0 ONE + v~1 e.0 + v~2 e.1 + ... + v~[n+1] e.n}
+@end ifnottex
+
+The previous code may be rewritten with the help of @code{lst_to_clifford()} as follows
@example
@{
@ifnottex
@samp{v = (v~0, v~1, ..., v~n)}
@end ifnottex
-such that
+such that the expression is either vector
@tex
$e = v^0 c_0 + v^1 c_1 + ... + v^n c_n$
@end tex
@ifnottex
@samp{e = v~0 c.0 + v~1 c.1 + ... + v~n c.n}
@end ifnottex
-with respect to the given Clifford units @code{c} and with none of the
-@samp{v~k} containing Clifford units @code{c} (of course, this
+or pseudo-vector
+@tex
+$v^0 {\bf 1} + v^1 e_0 + v^2 e_1 + ... + v^{n+1} e_n$
+@end tex
+@ifnottex
+@samp{v~0 ONE + v~1 e.0 + v~2 e.1 + ... + v~[n+1] e.n}
+@end ifnottex
+with respect to the given Clifford units @code{c}. Here none of the
+@samp{v~k} should contain Clifford units @code{c} (of course, this
may be impossible). This function can use an @code{algebraic} method
-(default) or a symbolic one. With the @code{algebraic} method the @samp{v~k} are calculated as
+(default) or a symbolic one. With the @code{algebraic} method the
+@samp{v~k} are calculated as
@tex
$(e c_k + c_k e)/c_k^2$. If $c_k^2$
@end tex
@code{\clifford[1]@{e@}^@{@{\nu@}@}}, where @code{1} is the
@code{representation_label} and @code{\nu} is the index of the
corresponding unit. This provides a flexible typesetting with a suitable
-defintion of the @code{\clifford} command. For example, the definition
+definition of the @code{\clifford} command. For example, the definition
@example
\newcommand@{\clifford@}[1][]@{@}
@end example
bool is_exactly_a<T>(const ex & e);
bool ex::info(unsigned flag);
unsigned ex::return_type() const;
-unsigned ex::return_type_tinfo() const;
+return_type_t ex::return_type_tinfo() const;
@end example
When the test made by @code{is_a<T>()} returns true, it is safe to call
large @code{subs()} operations significantly faster if you are not using
patterns. The second option, @code{subs_options::algebraic} enables
algebraic substitutions in products and powers.
-@ref{Pattern matching and advanced substitutions}, for more information
+@xref{Pattern matching and advanced substitutions}, for more information
about patterns and algebraic substitutions. The third option,
@code{subs_options::no_index_renaming} disables the feature that dummy
-indices are renamed if the subsitution could give a result in which a
+indices are renamed if the substitution could give a result in which a
dummy index occurs more than two times. This is sometimes necessary if
you want to use @code{subs()} to rename your dummy indices.
Notes:
-@itemize
+@itemize @bullet
@item Wildcards behave like symbols and are subject to the same algebraic
rules. E.g., @samp{$0+2*$0} is automatically transformed to @samp{3*$0}.
@item As shown in the last example, to use wildcards for indices you have to
@example
bool ex::match(const ex & pattern);
-bool ex::match(const ex & pattern, lst & repls);
+bool ex::match(const ex & pattern, exmap& repls);
@end example
This function returns @code{true} when the expression matches the pattern
and @code{false} if it doesn't. If used in the second form, the actual
-subexpressions matched by the wildcards get returned in the @code{repls}
-object as a list of relations of the form @samp{wildcard == expression}.
-If @code{match()} returns false, the state of @code{repls} is undefined.
-For reproducible results, the list should be empty when passed to
-@code{match()}, but it is also possible to find similarities in multiple
-expressions by passing in the result of a previous match.
+subexpressions matched by the wildcards get returned in the associative
+array @code{repls} with @samp{wildcard} as a key. If @code{match()}
+returns false, @code{repls} remains unmodified.
The matching algorithm works as follows:
> match((a+b)*(a+c),($1+b)*($1+c));
@{$1==a@}
> match((a+b)*(a+c),(a+$1)*(a+$2));
-@{$1==c,$2==b@}
+@{$1==b,$2==c@}
(Unpredictable. The result might also be [$1==c,$2==b].)
> match((a+b)*(a+c),($1+$2)*($1+$3));
(The result is undefined. Due to the sequential nature of the algorithm
The method
@example
-bool ex::find(const ex & pattern, lst & found);
+bool ex::find(const ex & pattern, exset& found);
@end example
works a bit like @code{has()} but it doesn't stop upon finding the first
Both @code{has()} and @code{subs()} take an optional argument to pass them
extra options. This section describes what happens if you give the former
the option @code{has_options::algebraic} or the latter
-@code{subs:options::algebraic}. In that case the matching condition for
+@code{subs_options::algebraic}. In that case the matching condition for
powers and multiplications is changed in such a way that they become
more intuitive. Intuition says that @code{x*y} is a part of @code{x*y*z}.
If you use these options you will find that
@code{(x^5*y^2*z).subs(x^2*y^2==c, subs_options::algebraic)} will return
@code{x*c^2*z}. This also works with negative powers:
@code{(x^(-3)*y^(-2)*z).subs(1/(x*y)==c, subs_options::algebraic)} will
-return @code{x^(-1)*c^2*z}. Note that this only works for multiplications
+return @code{x^(-1)*c^2*z}.
+
+@strong{Note:} this only works for multiplications
and not for locating @code{x+y} within @code{x+y+z}.
@cindex factorization
@cindex @code{sqrfree()}
-GiNaC still lacks proper factorization support. Some form of
-factorization is, however, easily implemented by noting that factors
-appearing in a polynomial with power two or more also appear in the
-derivative and hence can easily be found by computing the GCD of the
-original polynomial and its derivatives. Any decent system has an
-interface for this so called square-free factorization. So we provide
-one, too:
+Square-free decomposition is available in GiNaC:
@example
ex sqrfree(const ex & a, const lst & l = lst());
@end example
Note also, how factors with the same exponents are not fully factorized
with this method.
+@subsection Polynomial factorization
+@cindex factorization
+@cindex polynomial factorization
+@cindex @code{factor()}
+
+Polynomials can also be fully factored with a call to the function
+@example
+ex factor(const ex & a, unsigned int options = 0);
+@end example
+The factorization works for univariate and multivariate polynomials with
+rational coefficients. The following code snippet shows its capabilities:
+@example
+ ...
+ cout << factor(pow(x,2)-1) << endl;
+ // -> (1+x)*(-1+x)
+ cout << factor(expand((x-y*z)*(x-pow(y,2)-pow(z,3))*(x+y+z))) << endl;
+ // -> (y+z+x)*(y*z-x)*(y^2-x+z^3)
+ cout << factor(pow(x,2)-1+sin(pow(x,2)-1)) << endl;
+ // -> -1+sin(-1+x^2)+x^2
+ ...
+@end example
+The results are as expected except for the last one where no factorization
+seems to have been done. This is due to the default option
+@command{factor_options::polynomial} (equals zero) to @command{factor()}, which
+tells GiNaC to try a factorization only if the expression is a valid polynomial.
+In the shown example this is not the case, because one term is a function.
+
+There exists a second option @command{factor_options::all}, which tells GiNaC to
+ignore non-polynomial parts of an expression and also to look inside function
+arguments. With this option the example gives:
+@example
+ ...
+ cout << factor(pow(x,2)-1+sin(pow(x,2)-1), factor_options::all)
+ << endl;
+ // -> (-1+x)*(1+x)+sin((-1+x)*(1+x))
+ ...
+@end example
+GiNaC's factorization functions cannot handle algebraic extensions. Therefore
+the following example does not factor:
+@example
+ ...
+ cout << factor(pow(x,2)-2) << endl;
+ // -> -2+x^2 and not (x-sqrt(2))*(x+sqrt(2))
+ ...
+@end example
+Factorization is useful in many applications. A lot of algorithms in computer
+algebra depend on the ability to factor a polynomial. Of course, factorization
+can also be used to simplify expressions, but it is costly and applying it to
+complicated expressions (high degrees or many terms) may consume far too much
+time. So usually, looking for a GCD at strategic points in a calculation is the
+cheaper and more appropriate alternative.
@node Rational expressions, Symbolic differentiation, Polynomial arithmetic, Methods and functions
@c node-name, next, previous, up
@tex
$\pi$
@end tex
+@ifnottex
+@math{Pi}
+@end ifnottex
(for which there already exists the built-in constant @code{Pi})
using John Machin's amazing formula
@tex
@}
@end example
+@page
+
@node Built-in functions, Multiple polylogarithms, Symmetrization, Methods and functions
@c node-name, next, previous, up
@section Predefined mathematical functions
@tex
$\zeta(m_1,m_2,\ldots,m_k)$.
@end tex
+@ifnottex
+@command{\mbox@{Li@}_@{m_1,m_2,...,m_k@}(x_1,x_2,...,x_k)},
+@command{\mbox@{S@}_@{n,p@}(x)},
+@command{\mbox@{H@}_@{m_1,m_2,...,m_k@}(x)} and
+@command{\zeta(m_1,m_2,...,m_k)} (with the dots replaced by actual parameters).
+@end ifnottex
If @code{zeta} is an alternating zeta sum, i.e. @code{zeta(m,s)}, the indices with negative sign
are printed with a line above, e.g.
@tex
$\zeta(5,\overline{2})$.
@end tex
+@ifnottex
+@command{\zeta(5,\overline@{2@})}.
+@end ifnottex
The order of indices and arguments in the GiNaC @code{lst}s and in the output is the same.
Definitions and analytical as well as numerical properties of multiple polylogarithms
@tex
$\zeta(1,2)$ evaluates to infinity.
@end tex
-So in comparison to the referenced publications the order of indices and arguments for @code{Li}
-is reversed.
+@ifnottex
+@code{Li_@{m_1,m_2,m_3@}(x,1,1) = H_@{m_1,m_2,m_3@}(x)} and
+@code{Li_@{2,1@}(1,1) = zeta(2,1) = zeta(3)}, but
+@code{zeta(1,2)} evaluates to infinity.
+@end ifnottex
+So in comparison to the older ones of the referenced publications the order of
+indices and arguments for @code{Li} is reversed.
The functions only evaluate if the indices are integers greater than zero, except for the indices
@code{s} in @code{zeta} and @code{G} as well as @code{m} in @code{H}. Since @code{s}
@tex
$\zeta(\overline{3},4)$
@end tex
+@ifnottex
+@command{zeta(\overline@{3@},4)}
+@end ifnottex
and
@code{G(lst(a,b), lst(-1,1), c)} means
@tex
$G(a-0\epsilon,b+0\epsilon;c)$.
@end tex
+@ifnottex
+@command{G(a-0\epsilon,b+0\epsilon;c)}.
+@end ifnottex
The definition of @code{H} allows indices to be 0, 1 or -1 (in expanded notation) or equally to
be any integer (in compact notation). With GiNaC expanded and compact notation can be mixed,
e.g. @code{lst(0,0,-1,0,1,0,0)}, @code{lst(0,0,-1,2,0,0)} and @code{lst(-3,2,0,0)} are equivalent as
@tex
$\zeta(1)$.
@end tex
+@ifnottex
+@command{zeta(1)}.
+@end ifnottex
In long expressions this helps a lot with debugging, because you can easily spot
the divergencies. But on the other hand, you have to make sure for yourself, that no illegal
cancellations of divergencies happen.
that return respectively the complex conjugate, the real part and the
imaginary part of an expression. Complex conjugation works as expected
-for all built-in functinos and objects. Taking real and imaginary
+for all built-in functions and objects. Taking real and imaginary
parts has not yet been implemented for all built-in functions. In cases where
it is not known how to conjugate or take a real/imaginary part one
of the functions @code{conjugate}, @code{real_part} or @code{imag_part}
@code{y} you defined in your program and there is no way to specify the
desired symbols to the @code{>>} stream input operator.
-Instead, GiNaC lets you construct an expression from a string, specifying the
-list of symbols to be used:
+Instead, GiNaC lets you read an expression from a stream or a string,
+specifying the mapping between the input strings and symbols to be used:
@example
@{
- symbol x("x"), y("y");
- ex e("2*x+sin(y)", lst(x, y));
+ symbol x, y;
+ symtab table;
+ table["x"] = x;
+ table["y"] = y;
+ parser reader(table);
+ ex e = reader("2*x+sin(y)");
@}
@end example
The input syntax is the same as that used by @command{ginsh} and the stream
-output operator @code{<<}. The symbols in the string are matched by name to
-the symbols in the list and if GiNaC encounters a symbol not specified in
-the list it will throw an exception.
+output operator @code{<<}. Matching between the input strings and expressions
+is given by @samp{table}. The @samp{table} in this example instructs GiNaC
+to substitute any input substring ``x'' with symbol @code{x}. Likewise,
+the substring ``y'' will be replaced with symbol @code{y}. It's also possible
+to map input (sub)strings to arbitrary expressions:
+
+@example
+@{
+ symbol x, y;
+ symtab table;
+ table["x"] = x+log(y)+1;
+ parser reader(table);
+ ex e = reader("5*x^3 - x^2");
+ // e = 5*(x+log(y)+1)^3 + (x+log(y)+1)^2
+@}
+@end example
+
+If no mapping is specified for a particular string GiNaC will create a symbol
+with corresponding name. Later on you can obtain all parser generated symbols
+with @code{get_syms()} method:
+
+@example
+@{
+ parser reader;
+ ex e = reader("2*x+sin(y)");
+ symtab table = reader.get_syms();
+ symbol x = reader["x"];
+ symbol y = reader["y"];
+@}
+@end example
-With this constructor, it's also easy to implement interactive GiNaC programs:
+Sometimes you might want to prevent GiNaC from inserting these extra symbols
+(for example, you want treat an unexpected string in the input as an error).
+
+@example
+@{
+ symtab table;
+ table["x"] = symbol();
+ parser reader(table);
+ parser.strict = true;
+ ex e;
+ try @{
+ e = reader("2*x+sin(y)");
+ @} catch (parse_error& err) @{
+ cerr << err.what() << endl;
+ // prints "unknown symbol "y" in the input"
+ @}
+@}
+@end example
+
+With this parser, it's also easy to implement interactive GiNaC programs:
@example
#include <iostream>
int main()
@{
- symbol x("x");
- string s;
-
- cout << "Enter an expression containing 'x': ";
- getline(cin, s);
-
- try @{
- ex e(s, lst(x));
- cout << "The derivative of " << e << " with respect to x is ";
- cout << e.diff(x) << ".\n";
- @} catch (exception &p) @{
- cerr << p.what() << endl;
- @}
+ cout << "Enter an expression containing 'x': " << flush;
+ parser reader;
+
+ try @{
+ ex e = reader(cin);
+ symtab table = reader.get_syms();
+ symbol x = table.find("x") != table.end() ?
+ ex_to<symbol>(table["x"]) : symbol("x");
+ cout << "The derivative of " << e << " with respect to x is ";
+ cout << e.diff(x) << "." << endl;
+ @} catch (exception &p) @{
+ cerr << p.what() << endl;
+ @}
@}
@end example
@cindex Monte Carlo integration
@code{FUNCP_2P} allows for two variables in the expression. @code{FUNCP_CUBA} is
the correct type to be used with the CUBA library
-(@uref{http://www.feynarts/cuba}) for numerical integrations. The details for the
+(@uref{http://www.feynarts.de/cuba}) for numerical integrations. The details for the
parameters of @code{FUNCP_CUBA} are explained in the CUBA manual.
@cindex compile_ex
function before calling the @code{evalf_func()}.
@example
-set_return_type(unsigned return_type, unsigned return_type_tinfo)
+set_return_type(unsigned return_type, const return_type_t * return_type_tinfo)
@end example
This allows you to explicitly specify the commutation properties of the
function (@xref{Non-commutative objects}, for an explanation of
-(non)commutativity in GiNaC). For example, you can use
-@code{set_return_type(return_types::noncommutative, TINFO_matrix)} to make
-GiNaC treat your function like a matrix. By default, functions inherit the
-commutation properties of their first argument.
+(non)commutativity in GiNaC). For example, with an object of type
+@code{return_type_t} created like
+
+@example
+return_type_t my_type = make_return_type_t<matrix>();
+@end example
+
+you can use @code{set_return_type(return_types::noncommutative, &my_type)} to
+make GiNaC treat your function like a matrix. By default, functions inherit the
+commutation properties of their first argument. The utilized template function
+@code{make_return_type_t<>()}
+
+@example
+template<typename T> inline return_type_t make_return_type_t(const unsigned rl = 0)
+@end example
+
+can also be called with an argument specifying the representation label of the
+non-commutative function (see section on dirac gamma matrices for more
+details).
@example
set_symmetry(const symmetry & s)
you enough information so you can consult the source to GiNaC's predefined
classes if you want to implement something more complicated.
-@subsection GiNaC's run-time type information system
+@subsection Hierarchy of algebraic classes.
@cindex hierarchy of classes
-@cindex RTTI
All algebraic classes (that is, all classes that can appear in expressions)
in GiNaC are direct or indirect subclasses of the class @code{basic}. So a
-@code{basic *} (which is essentially what an @code{ex} is) represents a
-generic pointer to an algebraic class. Occasionally it is necessary to find
-out what the class of an object pointed to by a @code{basic *} really is.
-Also, for the unarchiving of expressions it must be possible to find the
-@code{unarchive()} function of a class given the class name (as a string). A
-system that provides this kind of information is called a run-time type
-information (RTTI) system. The C++ language provides such a thing (see the
-standard header file @file{<typeinfo>}) but for efficiency reasons GiNaC
-implements its own, simpler RTTI.
-
-The RTTI in GiNaC is based on two mechanisms:
-
+@code{basic *} represents a generic pointer to an algebraic class. Working
+with such pointers directly is cumbersome (think of memory management), hence
+GiNaC wraps them into @code{ex} (@pxref{Expressions are reference counted}).
+To make such wrapping possible every algebraic class has to implement several
+methods. Visitors (@pxref{Visitors and tree traversal}), printing, and
+(un)archiving (@pxref{Input/output}) require helper methods too. But don't
+worry, most of the work is simplified by the following macros (defined
+in @file{registrar.h}):
@itemize @bullet
+@item @code{GINAC_DECLARE_REGISTERED_CLASS}
+@item @code{GINAC_IMPLEMENT_REGISTERED_CLASS}
+@item @code{GINAC_IMPLEMENT_REGISTERED_CLASS_OPT}
+@end itemize
-@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_}.
+The @code{GINAC_DECLARE_REGISTERED_CLASS} macro inserts declarations
+required for memory management, visitors, printing, and (un)archiving.
+It takes the name of the class and its direct superclass as arguments.
+The @code{GINAC_DECLARE_REGISTERED_CLASS} should be the first line after
+the opening brace of the class definition.
-@item
-By means of some clever tricks with static members, GiNaC maintains a list
-of information for all classes derived from @code{basic}. The information
-available includes the class names, the @code{tinfo_key}s, and pointers
-to the unarchiving functions. This class registry is defined in the
-@file{registrar.h} header file.
+@code{GINAC_IMPLEMENT_REGISTERED_CLASS} takes the same arguments as
+@code{GINAC_DECLARE_REGISTERED_CLASS}. It initializes certain static
+members of a class so that printing and (un)archiving works. The
+@code{GINAC_IMPLEMENT_REGISTERED_CLASS} may appear anywhere else in
+the source (at global scope, of course, not inside a function).
-@end itemize
-
-The disadvantage of this proprietary RTTI implementation is that there's
-a little more to do when implementing new classes (C++'s RTTI works more
-or less automatically) but don't worry, most of the work is simplified by
-macros.
+@code{GINAC_IMPLEMENT_REGISTERED_CLASS_OPT} is a variant of
+@code{GINAC_IMPLEMENT_REGISTERED_CLASS}. It allows specifying additional
+options, such as custom printing functions.
@subsection A minimalistic example
placing character strings in algebraic expressions (this is not very useful,
but it's just an example). This class will be a direct subclass of
@code{basic}. You can use this sample implementation as a starting point
-for your own classes.
+for your own classes @footnote{The self-contained source for this example is
+included in GiNaC, see the @file{doc/examples/mystring.cpp} file.}.
The code snippets given here assume that you have included some header files
as follows:
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:
+object from a string:
@example
class mystring : public basic
GINAC_DECLARE_REGISTERED_CLASS(mystring, basic)
public:
- mystring(const string &s);
- mystring(const char *s);
+ mystring(const string & s);
private:
string str;
GINAC_IMPLEMENT_REGISTERED_CLASS(mystring, basic)
@end example
-The @code{GINAC_DECLARE_REGISTERED_CLASS} and @code{GINAC_IMPLEMENT_REGISTERED_CLASS}
-macros are defined in @file{registrar.h}. They take the name of the class
-and its direct superclass as arguments and insert all required declarations
-for the RTTI system. The @code{GINAC_DECLARE_REGISTERED_CLASS} should be
-the first line after the opening brace of the class definition. The
-@code{GINAC_IMPLEMENT_REGISTERED_CLASS} may appear anywhere else in the
-source (at global scope, of course, not inside a function).
-
-@code{GINAC_DECLARE_REGISTERED_CLASS} contains, among other things the
-declarations of the default constructor and a couple of other functions that
-are required. It also defines a type @code{inherited} which refers to the
-superclass so you don't have to modify your code every time you shuffle around
-the class hierarchy. @code{GINAC_IMPLEMENT_REGISTERED_CLASS} registers the
-class with the GiNaC RTTI (there is also a
-@code{GINAC_IMPLEMENT_REGISTERED_CLASS_OPT} which allows specifying additional
-options for the class, and which we will be using instead in a few minutes).
-
-Now there are seven member functions we have to implement to get a working
+The @code{GINAC_DECLARE_REGISTERED_CLASS} macro insert declarations required
+for memory management, visitors, printing, and (un)archiving.
+@code{GINAC_IMPLEMENT_REGISTERED_CLASS} initializes certain static members
+of a class so that printing and (un)archiving works.
+
+Now there are three member functions we have to implement to get a working
class:
@itemize
@item
@code{mystring()}, the default constructor.
-@item
-@code{void archive(archive_node &n)}, the archiving function. This stores all
-information needed to reconstruct an object of this class inside an
-@code{archive_node}.
-
-@item
-@code{mystring(const archive_node &n, lst &sym_lst)}, the unarchiving
-constructor. This constructs an instance of the class from the information
-found in an @code{archive_node}.
-
-@item
-@code{ex unarchive(const archive_node &n, lst &sym_lst)}, the static
-unarchiving function. It constructs a new instance by calling the unarchiving
-constructor.
-
@item
@cindex @code{compare_same_type()}
-@code{int compare_same_type(const basic &other)}, which is used internally
+@code{int compare_same_type(const basic & other)}, which is used internally
by GiNaC to establish a canonical sort order for terms. It returns 0, +1 or
-1, depending on the relative order of this object and the @code{other}
object. If it returns 0, the objects are considered equal.
defined.
@item
-And, of course, @code{mystring(const string &s)} and @code{mystring(const char *s)}
-which are the two constructors we declared.
+And, of course, @code{mystring(const string& s)} which is the constructor
+we declared.
@end itemize
Let's proceed step-by-step. The default constructor looks like this:
@example
-mystring::mystring() : inherited(TINFO_mystring) @{@}
+mystring::mystring() @{ @}
@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
-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
-(remember that in our case @code{inherited == basic}). If the superclass
-didn't have such a constructor, we would have to set the @code{tinfo_key}
-to the right value manually.
-
In the default constructor you should set all other member variables to
reasonable default values (we don't need that here since our @code{str}
member gets set to an empty string automatically).
-Next are the three functions for archiving. You have to implement them even
-if you don't plan to use archives, but the minimum required implementation
-is really simple. First, the archiving function:
-
-@example
-void mystring::archive(archive_node &n) const
-@{
- inherited::archive(n);
- n.add_string("string", str);
-@}
-@end example
-
-The only thing that is really required is calling the @code{archive()}
-function of the superclass. Optionally, you can store all information you
-deem necessary for representing the object into the passed
-@code{archive_node}. We are just storing our string here. For more
-information on how the archiving works, consult the @file{archive.h} header
-file.
-
-The unarchiving constructor is basically the inverse of the archiving
-function:
-
-@example
-mystring::mystring(const archive_node &n, lst &sym_lst) : inherited(n, sym_lst)
-@{
- n.find_string("string", str);
-@}
-@end example
-
-If you don't need archiving, just leave this function empty (but you must
-invoke the unarchiving constructor of the superclass). Note that we don't
-have to set the @code{tinfo_key} here because it is done automatically
-by the unarchiving constructor of the @code{basic} class.
-
-Finally, the unarchiving function:
-
-@example
-ex mystring::unarchive(const archive_node &n, lst &sym_lst)
-@{
- return (new mystring(n, sym_lst))->setflag(status_flags::dynallocated);
-@}
-@end example
-
-You don't have to understand how exactly this works. Just copy these
-four lines into your code literally (replacing the class name, of
-course). It calls the unarchiving constructor of the class and unless
-you are doing something very special (like matching @code{archive_node}s
-to global objects) you don't need a different implementation. For those
-who are interested: setting the @code{dynallocated} flag puts the object
-under the control of GiNaC's garbage collection. It will get deleted
-automatically once it is no longer referenced.
-
Our @code{compare_same_type()} function uses a provided function to compare
the string members:
@example
-int mystring::compare_same_type(const basic &other) const
+int mystring::compare_same_type(const basic & other) const
@{
const mystring &o = static_cast<const mystring &>(other);
int cmpval = str.compare(o.str);
are considered equal (in the sense that @math{A-B=0}), so you should compare
all relevant member variables.
-Now the only thing missing is our two new constructors:
+Now the only thing missing is our constructor:
@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) : str(s) @{ @}
@end example
-No surprises here. We set the @code{str} member from the argument and
-remember to pass the right @code{tinfo_key} to the @code{basic} constructor.
+No surprises here. We set the @code{str} member from the argument.
That's it! We now have a minimal working GiNaC class that can store
strings in algebraic expressions. Let's confirm that the RTTI works:
@{
...
protected:
- void do_print(const print_context &c, unsigned level = 0) const;
+ void do_print(const print_context & c, unsigned level = 0) const;
...
@};
-void mystring::do_print(const print_context &c, unsigned level) const
+void mystring::do_print(const print_context & c, unsigned level) const
@{
// print_context::s is a reference to an ostream
c.s << '\"' << str << '\"';
ex mystring::eval(int level) const
@{
string new_str;
- for (int i=0; i<str.length(); i++) @{
+ for (size_t i=0; i<str.length(); i++) @{
char c = str[i];
if (c >= 'A' && c <= 'Z')
new_str += tolower(c);
@cindex @code{is_equal_same_type()}
@example
unsigned calchash() const;
-bool is_equal_same_type(const basic &other) const;
+bool is_equal_same_type(const basic & other) const;
@end example
The @code{calchash()} method returns an @code{unsigned} hash value for the
That's it. May the source be with you!
+@subsection Upgrading extension classes from older version of GiNaC
+
+GiNaC used to use a custom run time type information system (RTTI). It was
+removed from GiNaC. Thus, one needs to rewrite constructors which set
+@code{tinfo_key} (which does not exist any more). For example,
+
+@example
+myclass::myclass() : inherited(&myclass::tinfo_static) @{@}
+@end example
+
+needs to be rewritten as
+
+@example
+myclass::myclass() @{@}
+@end example
@node A comparison with other CAS, Advantages, Adding classes, Top
@c node-name, next, previous, up
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, factorization,
+respect to mathematical features. Integration,
non-trivial simplifications, limits etc. are missing in GiNaC (and are
not planned for the near future).
and exponent and some atomic leaves of symbols and numbers in this
fashion:
+@ifnotinfo
@image{repnaive}
+@end ifnotinfo
+@ifinfo
+<PICTURE MISSING>
+@end ifinfo
@cindex pair-wise representation
However, doing so results in a rather deeply nested tree which will
having a numeric exponent and a possibly complicated base, the tree
becomes much more flat:
+@ifnotinfo
@image{reppair}
+@end ifnotinfo
+@ifinfo
+<PICTURE MISSING>
+@end ifinfo
The number @code{3} above the symbol @code{d} shows that @code{mul}
objects are treated similarly where the coefficients are interpreted as
@math{2*d^3*(4*a+5*b-3)}:
@end ifnottex
+@ifnotinfo
@image{repreal}
+@end ifnotinfo
+@ifinfo
+<PICTURE MISSING>
+@end ifinfo
@cindex radical
This also allows for a better handling of numeric radicals, since
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:
@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}
+@subsection Configuring a package that uses GiNaC
-Simply make sure that @command{ginac-config} is in your path, and run
-the configure script.
-
-Notes:
-
-@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
-
-@display
-editing @file{/etc/ld.so.conf} and running @command{ldconfig}
-@end display
+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*}.
-or by
-
-@display
-setting the environment variable @env{LD_LIBRARY_PATH},
-@end display
+The short summary below describes how to do this on a GNU/Linux
+system.
-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 <iostream>
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:
+
+Requested 'ginac >= 1.3.7' but version of GiNaC is 1.3.5
-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'
+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.
## 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
git://www.ginac.de / ginac.git / blobdiff