\documentclass[a4paper]{article}
\usepackage[latin1]{inputenc}

\newcommand{\link}[2]{#1}
\newcommand{\gpcc}{{\tt gp2c}}
%HEVEA \renewcommand{\link}[2]{\ahref{#2}{#1}}
%Use \gpcc only for large fonts.(titles, sections)
\newcommand{\pathlink}[1]{\link{\path{#1}}{#1}}
\newcommand{\path}[1]{\texttt{#1}}
\newcommand{\gp}[1]{\textit{#1}}
\newcommand{\pari}[1]{\textsf{#1}}
\newcommand{\cmd}[1]{{\noindent\bf #1}}
\title{An introduction to \gpcc}
\author{By Bill Allombert and Ariel Pacetti}

\begin{document}
\maketitle
\tableofcontents
\section{What is \gpcc ?}

The \path{gp2c} compiler is a package for translating GP routines into the C
programming language, so that they can be compiled and used with the
\link{PARI}{http://pari.math.u-bordeaux.fr} system or the GP calculator.

The main advantage of doing this is to speed up computations and
to include your own routines within the preexisting GP ones. It may also
find bugs in GP scripts.

This package (including the latest versions) can be obtained at the
URL:\\
\pathlink{http://pari.math.u-bordeaux.fr/download.html\#gp2c}

\subsection{Installing \gpcc}

After downloading the file \path{gp2c-\emph{x.y.z}pl\emph{t}.tar.gz} (where
\emph{x,y,z} and \emph{t} depend on the version), you first have to unzip the
file with the command:

\cmd{gunzip gp2c-\emph{x.y.z}pl\emph{t}.tar.gz}

This will create the new file \path{gp2c-\emph{x.y.z}pl\emph{t}.tar}.
Next you have to extract the files with the \cmd{tar} program:

\cmd{tar -xvf gp2c-\emph{x.y.z}pl\emph{t}.tar}

Note: You can do both steps at once with GNU \cmd{tar} by using the command:

\cmd{tar -zxvf gp2c-\emph{x.y.z}pl\emph{t}.tar.gz}

This creates a directory \path{gp2c-\emph{x.y.z}pl\emph{t}}, which contains the
main \gpcc\ files. Now you have to install the program.

You need the file \path{pari.cfg}.  This file can be found in the PARI object
directory and is installed in \$prefix/lib/pari/.

Copy or link this file in the \path{gp2c} directory, be sure to call it
\path{pari.cfg}.

\cmd{ln -s .../lib/pari/pari.cfg pari.cfg}

Run \cmd{./configure}, which will search for the PARI version and some
other configuration tools of the system. To install the program, type
\cmd{make}, and the program will be compiled. You can then run \cmd{make check} to verify that everything has gone fine (a bunch of OK's should show up).
All of this is completely standard, and you are now ready to use \gpcc.

You can use \path{gp2c} directly from this directory or you can install it by
running \cmd{make install} as root. If you do not install it, you can run it
from the \path{gp2c} directory by typing \cmd{./gp2c}

\section{A \gpcc\ tutorial}

\subsection{How can I compile and run my scripts?}\label{compile_and_run}

The simplest way to use \path{gp2c} is to call \path{gp2c-run}. If you want to
know what happens in detail, see next section.

To make the examples easier to follow, please move to the \path{gp2c} directory
and link the root of your PARI source there:

\cmd{ln -s .../pari .}

As an example, we will take the file \path{pari/examples/squfof.gp}, which is a
simple implementation of the well-known SQUFOF factoring method of D.~Shanks.

We just run the command:

\cmd{./gp2c-run pari/examples/squfof.gp}

After a little processing we get a GP session. But this session is special,
because it contains the compiled \gp{squfof} function. Hence we can do the
following:

\begin{verbatim}
parisize = 4000000, primelimit = 500000
? squfof(3097180303181)
[419]
i = 596
Qfb(133225, 1719841, -261451, 0.E-28)
%1 = 1691693
\end{verbatim}
Let's try a bigger example:
\begin{verbatim}
? squfof(122294051504814979)
[20137]
  ***   the PARI stack overflows !
  current stack size: 4.0 Mbytes
  [hint] you can increase GP stack with allocatemem()
? allocatemem()
  ***   Warning: doubling stack size; new stack = 8.0 MBytes.
? squfof(122294051504814979)
[20137]
[20137, 3445]
i = 46474
Qfb(321233929, 131349818, -367273962, 0.E-28)
%2 = 73823023
\end{verbatim}
We need a large stack because by default \path{gp2c} does not generate code to
handle the stack (the so-called \pari{gerepile} code). To instruct \path{gp2c}
to add \path{gerepile} code automatically, we must use the \cmd{-g} option.
So quit this GP session and launch a new one with -g. Oh well, before that type

\cmd{ls pari/examples/squfof.gp*}
\begin{verbatim}
pari/examples/squfof.gp    pari/examples/squfof.gp.run
pari/examples/squfof.gp.c  pari/examples/squfof.gp.so
pari/examples/squfof.gp.o
\end{verbatim}

These are the files generated by \path{gp2c-run}:
\begin{itemize}
\item pari/examples/squfof.gp.c is the C file generated by \path{gp2c}.
\item pari/examples/squfof.gp.o is the object file generated by the C compiler.
\item pari/examples/squfof.gp.so is the shared library generated by the linker.
\item pari/examples/squfof.gp.run is a file that contains the commands needed
to load the compiled functions inside GP.
\end{itemize}
It is the shared library which is used by GP.

Now let's continue:

\cmd{./gp2c-run -g pari/examples/squfof.gp}
\begin{verbatim}
parisize = 4000000, primelimit = 500000
? squfof(122294051504814979)
[20137]
[20137, 3445]
i = 46474
Qfb(321233929, 131349818, -367273962, 0.E-28)
%1 = 73823023
\end{verbatim}

This time it works with no difficulty using the default stack. We would like
to know how much faster the compiled code runs, so we need to load the non
compiled \gp{squfof} file in GP:

\begin{verbatim}
? \r pari/examples/squfof.gp
  ***   unexpected character: squfof(n)=if(isprime(n),retur
                                       ^--------------------
\end{verbatim}
Why?? Because \gp{squfof} already exists as an installed function and GP
refuses to overwrite it. To solve this problem, we will add a suffix to the
name of the compiled function under GP.  Quit the session and type:

\cmd{./gp2c-run -g -s\_c pari/examples/squfof.gp}

Now the function squfof is named squfof\_c instead, so we can do
\begin{verbatim}
parisize = 4000000, primelimit = 500000
? \r pari/examples/squfof.gp
? #
   timer = 1 (on)
? squfof(122294051504814979)
[20137]
[20137, 3445]
i = 46474
Qfb(321233929, 131349818, -367273962, 0.E-28)
time = 5,810 ms.
%1 = 73823023
? squfof_c(122294051504814979)
[20137]
[20137, 3445]
i = 46474
Qfb(321233929, 131349818, -367273962, 0.E-28)
time = 560 ms.
%2 = 73823023
\end{verbatim}
So the compiled version is more than ten times faster than the noncompiled one.
However for more complex examples, compiled code usually runs only
three times faster on average.

An extra trick: once you have run \path{gp2c-run} on your script, it is
compiled and you can use the compiled version outside \path{gp2c-run} in any GP
session by loading the file with extension \path{.gp.run}. For example quit the
\path{gp2c-run} session and start \path{gp} and do

\begin{verbatim}
parisize = 4000000, primelimit = 500000
? \r pari/examples/squfof.gp.run
\end{verbatim}

Now you have access to the compiled function \gp{squfof\_c} as well.

\subsection{How can I compile directly with \gpcc ?}\label{compile_directly}

Now we want to compile directly with \path{gp2c} to understand what happens.
We should run the command

{\bf ./gp2c pari/examples/squfof.gp \verb!>! squfof.gp.c}


This creates a file squfof.gp.c in the \path{gp2c} directory. Now read this
file with your favorite editor.

The first line is highly system-dependent, but should be similar to:

{\small \begin{verbatim}
/*-*- compile-command: "/usr/bin/gcc -c -o pari/examples/squfof.gp.o
  -O3 -Wall -I/usr/local/include pari/examples/squfof.gp.c
  && /usr/bin/gcc -o pari/examples/squfof.gp.so
  -shared   pari/examples/squfof.gp.o"; -*-*/
\end{verbatim} }
This is the command needed to compile this C file to an object file with the
C compiler and then to make a shared library with the linker. If you use
\path{emacs}, typing 'M-x compile' will know about this command, so you will
just need to type {\tt Return} to compile.

The second line is
\begin{verbatim}
#include <pari/pari.h>
\end{verbatim}
This includes the PARI header files. It is important that the header files come
from the same PARI version as GP, else it will create problems.

The next lines are
{\small \begin{verbatim}
/*
GP;install("squfof","D0,G,p","squfof","./pari/examples/squfof.gp.so");
GP;install("init_squfof","v","init_squfof","./pari/.../squfof.gp.so");
*/
\end{verbatim} }

The characters "GP;" denote a command that should be read by GP at start-up.
Here, the \gp{install()} commands above must be given to GP to let it know
about functions defined by the library. \path{gp2c-run} copy such commands
to the file \path{./pari/examples/squfof.gp.run}.

Please read the entry about the \gp{install()} command in the PARI manual.

The \gp{init\_squfof} function is an initialization function that is created
automatically by \gpcc\ to hold codes that is outside any function. Since
in our case there are none, this is a dummy function. In other cases, it is
essential. The next lines are

\begin{verbatim}
GEN squfof(GEN n, long prec);
void init_squfof(void);
/*End of prototype*/
\end{verbatim}
This is the C prototypes of your functions. The rest of the file is
the C code proper.

For teaching purpose, let's run the command

{\bf ./gp2c -s\_c pari/examples/squfof.gp \verb!>! squfof2.gp.c}

and look at the difference between squfof.gp.c and squfof2.gp.c:

\cmd{diff -u squfof.gp.c squfof2.gp.c}
{\small \begin{verbatim}
--- squfof.gp.c Tue Feb 26 13:44:42 2002
+++ squfof2.gp.c        Tue Feb 26 13:44:49 2002
@@ -1,8 +1,8 @@
 /*-*- compile-command: "/usr/bin/gcc -c -o pari/examples/squfof.gp.o
  -DMEMSTEP=1048576 -g -Wall -Wno-implicit  -I/usr/local/include
  pari/examples/squfof.gp.c && /usr/bin/ld -o pari/examples/squfof.gp.so
  -shared   pari/examples/squfof.gp.o"; -*-*/
 #include <pari/pari.h>
 /*
-GP;install("squfof","D0,G,p","squfof","./pari/examples/squfof.gp.so");
-GP;install("init_squfof","v","init_squfof","./pari/.../squfof.gp.so");
+GP;install("squfof","D0,G,p","squfof_c","./pari/...les/squfof.gp.so");
+GP;install("init_squfof","v","init_squfof_c","./par.../squfof.gp.so");
 */
 GEN squfof(GEN n, long prec);
 void init_squfof(void);
\end{verbatim} }
If you are not familiar with the \path{diff} utility, the above means that only
the two lines starting with \gp{GP;install} have changed. In fact \gp{squfof} is
still named \gp{squfof} in the C file, but the install command tells GP to
rename it \gp{squfof\_c} in the GP session.

\subsection{Using \gpcc\ to find errors in GP scripts}\label{find_errors}

The \path{gp2c} compiler can also be used to find errors in GP programs. For
that we should use the -W option like in

{\bf ./gp2c -W pari/examples/squfof.gp \verb!>! squfof.gp.c}
\begin{verbatim}
Warning:pari/examples/squfof.gp:7:variable undeclared
p
Warning:pari/examples/squfof.gp:11:variable undeclared
dd
Warning:pari/examples/squfof.gp:11:variable undeclared
d
Warning:pari/examples/squfof.gp:11:variable undeclared
b
...
Warning:pari/examples/squfof.gp:45:variable undeclared
b1
\end{verbatim}

This option lists variables that are used but not declared. It is important
to declare all your variables with \gp{my()}, or with \gp{global()}.
For \gpcc , undeclared variables are taken to be ``formal variables'' for
polynomials. For example if you write a function to build a second degree
polynomial like
\begin{center}
\verb!pol(a,b,c)=a*x^2+b*x+c!
\end{center}
you must not declare 'x' here, since it stands for the formal variable \gp{x}.

\subsection{Using compiled functions in a new program}\label{compiled_in_new_program}

One you have successfully compiled and tested your functions you may want to
reuse them in another GP program.

The best way is to copy the install commands of the functions you use at the
start of the new program so that reading it will automatically load the
compiled functions.

As an example, we write a simple program \path{fact.gp} that reads
{\small \begin{verbatim}
install("squfof","D0,G,p","squfof","./pari/examples/squfof.gp.so");
fact_mersenne(p)=squfof(2^p-1)
\end{verbatim} }
and run GP:
\begin{verbatim}
parisize = 4000000, primelimit = 500000
? \rfact
? fact_mersenne(67)
i = 2418
Qfb(10825778209, 4021505768, -13258245519, 0.E-28)
%1 = 193707721
\end{verbatim}

So all goes well. But what is even better is that \gpcc\ understands the
\gp{install} command and will be able to compile this new program.

Also this particular example will fail because as stated above, PARI/GP already
has a \pari{squfof} function, and the linker will pick the wrong one, which is
unfortunate.

So use the -p option to \path{gp2c-run} to change \gp{squfof} to
\gp{my\_squfof}.

\cmd{ ./gp2c-run -pmy\_ -g pari/examples/squfof.gp}

This option prefixes my\_ to every GP name in the program so as to
avoid name clashes. Change \path{fact.gp} to
{\small \begin{verbatim}
install("my_squfof","D0,G,p","squfof","./pari/examples/squfof.gp.so");
fact_mersenne(p)=squfof(2^p-1)
\end{verbatim} }
and run

\cmd{./gp2c-run -g fact.gp}
\begin{verbatim}
parisize = 4000000, primelimit = 500000
? fact_mersenne(67)
i = 2418
Qfb(10825778209, 4021505768, -13258245519, 0.E-28)
%1 = 193707721
\end{verbatim}

Nice isn't it?

But it gets even better: instead of writing the \gp{install} command directly
in your script you can just load the \path{squfof.gp.run} using
\verb!\r!: just change \path{fact.gp} to
{\small \begin{verbatim}
\r ./pari/examples/squfof.gp.run
fact_mersenne(p)=squfof(2^p-1)
\end{verbatim} }

\subsection{Hand-editing the C file generated by \gpcc}

If you have some experience in PARI programming, you may want to manually
edit the C file generated by \gpcc , for example to improve memory handling.
Here some tips:
\begin{itemize}
%\item The C file created with gp2c-run is name \textit{file}.gp.c. To avoid
%subsequent run of gp2c-run accidently clobbering it, it is advised to rename
%this file to \textit{file}.c, and change the \gp{install()}

\item If you preserve the \gp{install()} at the start of the file, you can use
the command \cmd{gp2c-run \textit{file}.c} to recompile your file and start a
new GP session with your functions added, just as you use \cmd{gp2c-run} with
GP scripts.

\item More generally, \cmd{gp2c-run} automatically passes any line in the C
file starting with 'GP;' to GP at start-up.

\item As explained in Section~\ref{compile_directly}, under \textbf{emacs} you
can type 'M-x compile' to recompile the shared library.
\end{itemize}
\section{Advanced use of \gpcc}\label{advanced}
\subsection {\gpcc\ types}

Internally \gpcc\ assign types to objects. The most common types
are given below:

\begin{tabular}{l|l}
name & description \\
\hline
\gp{void} & like in C \\
\gp{bool} & boolean, true (1) or false (0)  \\
\gp{negbool} & antiboolean, true (0) or false (1)  \\
\gp{small}& C integer \pari{long}       \\
\gp{int}  & multiprecision integer  \\
\gp{real} & multiprecision floating point \\
\gp{mp}   & multiprecision number \\
\gp{var}  & variable \\
\gp{pol}  & polynomial \\
\gp{vecsmall}  & vector of C long (\pari{t\_VECSMALL}) \\
\gp{vec}  & vector and matrices (excluding \gp{vecsmall})\\
\gp{list} & GP lists \\
\gp{str}  & characters string as a \pari{char *}\\
\gp{genstr} & characters string as a \pari{GEN} (\pari{t\_STR})\\
\gp{gen}  & generic PARI object (\pari{GEN})\\
\gp{lg}   & length of object (returned by \gp{length}) \\
\gp{typ}  & type of object (returned by \gp{type}) \\
\end{tabular}

\begin{table}[hbpt]
$$
%HEVEA \begin{toimage}
\unitlength=1.mm
\begin{picture}(12,50)(-6,0)
\put(6,50){\makebox[0mm]{gen}}
\put(6,44){\line(0,1){5}}
\put(6,40){\makebox[0mm]{mp}}
\put(-2,44){\line(1,1){5}}
\put(-3,40){\makebox[0mm]{vec}}
\put(-9,44){\line(2,1){12}}
\put(-9,40){\makebox[0mm]{pol}}
\put(-9,34){\line(0,1){5}}
\put(-9,30){\makebox[0mm]{var}}
\put(12,30){\makebox[-1.5mm]{real}}
\put(12,34){\line(-1,1){5}}
\put(0,30){\makebox[-1.5mm]{int}}
\put(0,34){\line(1,1){5}}
\put(0,20){\makebox[1mm]{small}}
\put(0,24){\line(0,1){5}}
\put(0,10){\makebox[1mm]{bool}}
\put(-8,17){\line(1,1){4}}
\put(-15,15){\makebox[1mm]{negbool}}
\put(-4,11){\line(-1,1){4}}
\put(0,14){\line(0,1){5}}
\put(0,00){\makebox[1mm]{void}}
\put(5,01){\line(1,4){7}}
\put(0,04){\line(0,1){5}}
\end{picture}
%HEVEA \end{toimage}
%HEVEA \imageflush
$$
\caption{Types preorder}\label{preorder}
\end{table}

Types are preordered as in Table~\ref{preorder}. The complete preorder
known by \gpcc\ can be accessed by running \cmd{gp2c -t}.

Variables are typed. A variable can only take values having a type equal or
lower than its type. By default, variables are of type \gp{gen}.

\subsection{Type declaration}

To declare a variable as belonging to type \gp{type}, use:
\begin{quote}
\textit{function}(x\textit{:type},y\textit{:type}=2) \\
my(x\textit{:type}, y\textit{:type}=2) \\
global(x\textit{:type}, y\textit{:type}=2) \\
for(i\textit{:type}=...
\end{quote}

To declare several variables of the same type \gp{type} at once, use:
\begin{quote}
my(x, y=2)\textit{:type}\\
global(x, y=2)\textit{:type}
\end{quote}

You can even mix the two ways:
\begin{quote}
my(x, y:\textit{type2}=2)\textit{:type1}
\end{quote}
will declare \gp{x} to be of type \gp{type1} and \gp{y} of type \gp{type2}.

\subsection{Effect of types declaration on default values}

Under GP, all GP variables start with a default value, which is \gp{0} for a
local variable and \gp{'v} for a global variable \gp{v}.

The \gpcc\ compiler follows this rule for variables declared without a type.
However, when a variable is declared with a type, \gpcc\ will not assign it a
default value.  This means that the declaration \gp{my(g)} is equivalent to
\gp{my(g:gen=0)}, but not to \gp{my(g:gen)}, \gp{my(g)} is equivalent
to \gp{my(g:gen='g)}, but not to \gp{my(g:gen)}, and \gp{f(g)=...} is
equivalent to \gp{f(g:gen=0)=...}, but not to \gp{f(g:gen)=...}.

This rule was chosen for several reasons:
\begin{itemize}
\item The default value (\gp{0} or \gp{'v}) might not be an object suitable for
the type in question.  For example, \gp{my(v:vec)} declares \gp{v} as being
of type \gp{vec}. It would make no sense to initialize \gp{v} to \gp{0} since
\gp{0} does not belong to type \gp{vec}. Similarly \gp{global(N:int)} declares
\gp{N} as being of type \gp{int}. It would make no sense to initialize \gp{N}
to \gp{'N} since \gp{'N} does not belong to type \gp{int}.

\item This allows defining GP functions with mandatory arguments.
This way, GP will issue an error if a mandatory argument is missing.
Without this rule, there is no way to tell apart \gp{0} from a missing argument.

\item This allows telling \gpcc\ not to generate useless default values.
\end{itemize}

\subsection{Type casting}

Sometimes, we know a more precise type than the one the transtyping algorithm
can derive. For example if \gp{x} is a real number, its logarithm might be
complex.  However, if we are sure \gp{x} is positive, the logarithm will be
real.

To force an expression to belong to type \gp{type}, use
the syntax: \\
\textit{expr}\textit{:type}\\
\gpcc\ will check types consistency and output warnings if necessary.
For example\\
\gp{f(x:int)=my(r:real); r=log(x\^{}2+1)}\\
\gpcc\ will complain that the logarithm might not be real.  Since \gp{x\^{}2+1}
is always positive, we can write:\\
\gp{f(x:int)=my(r:real); r=log(x\^{}2+1):real}

\subsection{Example of optimisation}

Declaring the types of variables allow \gpcc\ to perform some optimisations.
For example, the following piece of GP code

\begin{verbatim}

rho(n)=
{
  my(x,y);

  x=2; y=5;
  while(gcd(y-x,n)==1,
    x=(x^2+1)%n;
    y=(y^2+1)%n; y=(y^2+1)%n
   );
  gcd(n,y-x)
}
\end{verbatim}

generates the following output:

\begin{verbatim}
GEN
rho(GEN n)
{
  GEN x = gen_0, y = gen_0;
  x = gen_2;
  y = stoi(5);
  while (gequal1(ggcd(gsub(y, x), n)))
  {
    x = gmod(gaddgs(gsqr(x), 1), n);
    y = gmod(gaddgs(gsqr(y), 1), n);
    y = gmod(gaddgs(gsqr(y), 1), n);
  }
  return ggcd(n, gsub(y, x));
}
\end{verbatim}

The functions \pari{gsqr}, \pari{gaddgs}, \pari{gmod}, \pari{ggcd} are generic
PARI functions that handle \gp{gen} objects. Since we only want to factor
integers with this method, we can declare \gp{n}, \gp{x} \and \gp{y} of type
\gp{int}:

{\noindent\tt rho(n\textit{:int})=\\
\verb!{!\\
\verb!  my!(x\textit{:int},y\textit{:int});}
\begin{verbatim}
  x=2; y=5;
  while(gcd(y-x,n)==1,
    x=(x^2+1)%n;
    y=(y^2+1)%n; y=(y^2+1)%n
   );
  gcd(n,y-x)
}
\end{verbatim}

The new C code output by \gpcc\ is:

\begin{verbatim}
GEN
rho(GEN n)        /* int */
{
  GEN x, y;       /* int */
  if (typ(n) != t_INT)
    pari_err(typeer, "rho");
  x = gen_2;
  y = stoi(5);
  while (gequal1(gcdii(subii(y, x), n)))
  {
    x = modii(addis(sqri(x), 1), n);
    y = modii(addis(sqri(y), 1), n);
    y = modii(addis(sqri(y), 1), n);
  }
  return gcdii(n, subii(y, x));
}
\end{verbatim}

Now, the code now uses the more specific functions \pari{sqri}, \pari{addis},
\pari{modii} and \pari{gcdii}.

The most efficient way to use typing is to declare some variables of type
\gp{small}.  This way, these variables will be implemented by C \pari{long}
variables, which are faster than PARI integers and do not require garbage
collecting. However, you will not be protected from integer overflow.  For
that reason, \gpcc\ will automatically declare some loop indices of type
\gp{small} when the range cannot cause overflow. Sometimes \gpcc\ can be too
conservative but you can force a loop index to be \gp{small} with the syntax
\gp{for(i:small=a,b,...)}.

\subsection{Types and member functions}

For use with members functions, \gpcc\ provides the following types:

\begin{description}
\item[nf] for ordinary number fields, i.e., a result given by the GP function \gp{nfinit}.
\item[bnf] for big number fields, i.e., a result given by the GP function \gp{bnfinit} which includes class and unit group data.
\item[bnr] for ray class groups, i.e., a result given by the GP function \gp{bnrinit}.
\item[ell] for elliptic curves, i.e., a result given by the GP function \gp{ellinit}.
\item[gal] for galois extensions, i.e., a result given by the GP function \gp{galoisinit}.
\item[prid] for prime ideals, i.e., a component of the result given by the GP function \gp{idealprimedec}.
\end{description}

Members functions on typed objects are much more efficient.

\section{Common problems}
\subsection{Meta-commands.}

Meta-commands (commands starting with a \verb!\!) other than \verb!\r! are
currently ignored by \gpcc, though a warning will be issued, because it
is not clear what they should do in a compiled program. Instead you probably
want to run the meta-command in the GP session itself.

The meta-command \verb!\r!\textit{include} is replaced with the content of the
file \textit{include} (or \textit{include}.gp) when \gpcc\ reads the file.
If you would prefer \gpcc\ to link \textit{include}.so to the program instead,
see Section~\ref{compiled_in_new_program}.

\subsection{Unsupported functions.}\label{unsupported_funcs}

Some GP functions are not yet available to C programs, so the compiler cannot
handle them. If you use them you will get the error "unhandled letter in
prototype". These are currently \gp{forfactored} and \gp{forsquarefree}.

The functions \gp{forell}, \gp{forsubgroup} and \gp{forqfvec} are currently not
implemented as an iterator but as a procedure with callbacks, which limits what
you can do inside the loop.

The \gp{forstep} function is supported when the step is a number. If
it is a vector, you must add a tag \gp{:vec} to make GP know about it like in

\begin{verbatim}
f(x)=
{
  my(v);
  v=[2,4,6,6,6,6,6,2,4,6,6]
  forstep(y=7,x,v:vec,print(y))
}
\end{verbatim}

This is not needed if the step is a vector or a variable of type vec,
but is needed if the step is only an expression which evaluates to a vector.

Some functions are passed to GP by \path{gp2c-run} at start-up (using the
\pari{GP;} syntax) instead of being translated in C: \gp{install} and
\gp{addhelp}.  In practice, they can be considered as supported.

Also the functions \gp{read, eval, kill} may compile fine but have a
surprising behaviour in some case, because they may modify the state of the GP
interpreter, not of the compiled program. Please see
Section~\ref{global_variables} for details. For example
\verb!f(n)=eval("n^2")! is very different from \verb!f(n)=n^2!.
To read files at compile-time use \verb!\r! instead of \gp{read}.

\subsection{Dynamically-scoped local variables.}\label{dynamic_variables}

Currenlty \gpcc\ does not support dynamically-scoped local variables
declared with \gp{local()}. Instead \gp{local()} is treated as an
alias for \gp{my()} which declares statically-scoped local variables.

Supporting dynamically-scoped local variables is cumbersome to do in C.

\subsection{Memory handling and global variables.}\label{global_variables}

While a lot of work has been done to ensure that \gpcc\ handles global
variables properly, the use of global variables is still a lot of trouble, so
try to avoid them if you do not understand the implications on memory handling.

First, there is a common practice to use undeclared variables as formal
variables, for example we assume \gp{x='x} and write \gp{a*x+b} instead of
\gp{a*'x+b}. So \gpcc\ will not raise an undeclared variable to the rank of
global variable unless you declare it with the \gp{global()} command, or you
use it at toplevel (i.e. outside any function). See also
Section~\ref{find_errors}

Second, global variables seen by a compiled function are C variables, not GP
variables. There is no connection between the two. You may well have two
variables with the same name and a different content. Currently GP knows only
how to install functions, not variables, so you need to write compiled
functions in order to access global variables under GP.

Basically, global variables are allocated in the main stack which is destroyed
each time GP prints a new prompt. This means you must put all your commands on
the same line. Also global variables must be initialized using the
\gp{init\_}\verb!<filename>! function before being used, and are only supported
with the -g flag.

So you end up doing
\cmd{gp2c-run -g global.gp}
\begin{verbatim}
parisize = 4000000, primelimit = 500000
? init_global();myfunction(args);
\end{verbatim}

Note that nothing prevents you from calling \gp{init\_global} in the GP
program. In that case, you can omit the parentheses (i.e, write
\gp{init\_global}, not \gp{init\_global()}) so that you can still run your
noncompiled program.

Another way to handle global variables is to use the \gp{clone} function which
copies a PARI object to the heap, hence avoids its destruction when GP
prints a new prompt. You can use \gp{unclone} to free a clone. Please read the
PARI/GP manual for more information about \gp{clone}.

A good use of \gp{clone} is for initializing constant variables:
for example in \path{test/gp/initfunc.gp}, the vector \gp{T} is initialized by
\begin{verbatim}
T=clone([4,3,2,2,1,1,1,1,0,0,0,0,0,0,0,0])
\end{verbatim}
You must still run the \gp{init\_}\verb!<filename>! after starting GP, but after
that you can use \gp{T} safely.

GP itself currently does not know about \gp{clone} and \gp{unclone}, but you
can use dummy functions
\begin{verbatim}
clone(x)=x
unclone(x)=while(0,)
\end{verbatim}
when running uncompiled.

\subsection{Support for \pari{t\_VECSMALL}}
When accessing the component of a \pari{t\_VECSMALL}, it is necessary that
that the object has been declared of type \gp{vecsmall}.

For example \gp{ my(v); v = vecsort(V,,1); print(v[1]) } does not work, but
\gp{ my(v:vecsmall); v = vecsort(V,,1); print(v[1]) } or
\gp{ my(v:vecsmall); v = vecsort(V,,1); print(v:vecsmall[1]) } works.

\subsection{GP lists}

GP lists and maps are not fully supported by \gpcc .  A partial support is
available with the \gp{list} type.  You must tell \gpcc\ that a variable will
contain a list or a map by using \gp{L:list} inside a declaration, where \gp{L}
is the name of the variable as explained in Section~\ref{advanced}.

Currently, assigning to a list element (\gp{L[2]=x}) will not work and lists and
maps will not be freed unless you explicitly use \gp{listkill}.

Note: The PARI user's manual states that lists are useless in library mode.

\subsection{The \gp{install} command}

The \gp{install} command is interpreted as a \gpcc\ directive. This allows
using installed function in compiled programs, see
Section~\ref{compiled_in_new_program}.

However this has some side-effects:
\begin{itemize}
\item If present, the \gp{lib} argument must be a string, not an expression that
evaluate to a string.
\item The \gp{install} command is not compiled, instead it is added to the list
of functions to install.
\end{itemize}

\subsection{What about \pari{main()} ?}
There are two different issues with \pari{main()}: first this is reserved
function name in C, so using it with \gpcc\ will cause a name clash.
To avoid this, either rename it or use the flag -p.

Secondy \gpcc\ has no support for generating stand-alone GP programs.
However adding manually a \pari{main()} C function is not difficult in
general.

\section{Command-line options of \gpcc}

Here is a brief description of the main options of \path{gp2c}, which can be
seen with \path{./gp2c -h}.

In Section~\ref{compile_and_run} we saw how to use the \path{-g} option.
\begin{itemize}
\item -g tells \gpcc\ to generate \pari{gerepile} calls to clean up the
PARI stack and reduce memory usage. You will probably need this option,
although the C code will be easier to read or hand-edit without it.

\item -o\textit{file} tells \gpcc\ to write the generated C file
to the file \textit{file} instead of the standard output.

\item -iN allows you to change the indentation of the generated C
file. So if you want 4 spaces, just use the \path{-i4} option with
\path{gp2c}. The default is 2.

\item -C adds code to perform range checking for GP constructs like
\gp{x[a]} and \gp{x[a,b]}. This also checks whether \gp{x} has the
correct type. By default \gpcc\ does not perform such check, which can
lead to a runtime crash with invalid code. This option causes a small
runtime penalty and a large C code readability penalty.

\item -L adds compiler directives to the code so that warning and
error found by the compiler are prefixed with the line number in
the original GP file instead of the C file.

\item -W is useful for debugging the .gp file, in the sense
that it detects if some local variables are undeclared. For
example, if the file \path{algorithm.gp} has a routine like

\begin{verbatim}
radical(x)=F=factor(x)[,1];prod(i=1,length(F),F[i])
\end{verbatim}

The variable 'F' is undeclared in this routine, so when running
\path{gp2c} with the \path{-W} option it prints

\noindent{\bf Warning:algorithm.gp:1:variable undeclared F}

At present, an undeclared variable is taken to be a "formal variable" for
polynomials by \path{gp2c}, so do not declare it if that is what you intend.
For example in \verb!pol(a,b,c)=a*x^2+b*x+c! you must not declare \gp{x} since
it stands for the formal variable \gp{'x}.

\item -p\textit{prefix} A problem with C is that it is subject to name clashes,
i.e., if a GP variable in your routine has the same name as a C symbol
in the pari library, the compiler will report strange errors. So this option
changes ALL user variables and user routine names by adding a prefix
\textit{prefix} to them. For example the GP routine \gp{add(x,y)} with \cmd{-pmy\_} will become the C function \pari{my\_add(x,y)}.

Try this option each time the compiler fails to compile \path{gp2c} output to
see if there is a name conflict. If this is the case, change the name
in your GP script.
It may be difficult to find conflicting names if your compiler is not verbose
enough and if you are not familiar with the PARI code and C in general.

Example of conflicting names are \pari{top},\pari{bot},\pari{prec},\pari{un},
but there are thousands of others and they may be system-dependent.

\item -s\textit{suffix}: Add \textit{suffix} to the names of the installed
functions under GP. This is to avoid clashes with the original GP script. For
example, if you want to compare timings you may want to use the option
\cmd{-s\_c} This does not affect the C code, only the \gp{install} commands.

\item -S: Assume strict prototypes for functions. This is related to the
'strictargs' GP default. This makes all arguments of functions defined in
the file mandatory unless the function supplies an explicit default value.
This does not affect the C code, only the prototype code in the
\gp{install} commands.
In this example, the prototype code changes from "D0,G,DG" to "GDG".
\begin{verbatim}
test(data,flag=0)={CODE}
\end{verbatim}

\item -h gives the help.

\item -v gives the \gpcc\ version.

\item -l prints a list of all the GP functions known by the
compiler. So if a routine contains a GP routine not on this list, \path{gp2c}
will show an error when trying to translate it.

Reasons why a GP function may not be known by the compiler are:
\begin{itemize}

\item The function is not part of the PARI library. See
Section~\ref{unsupported_funcs}

\item You use the old PARI 1.39 function names instead of the new ones.
\gpcc\ currently does not know about the 'compat' default. Use
\gp{whatnow} under GP to get the current name. For example, \gp{mod()} is now
\gp{Mod()}.

\item You use a GP function that does not exists in the GP version \gpcc\
was compiled against. Please recompile \gpcc\ against this GP version.

Normally no functions are added between two stable releases of GP with the same
minor version number (say 2.1.1 and 2.1.2) so there is no need to recompile
\gpcc\ when you upgrade. But if you use the developement versions, you
need to recompile. Also some new developement versions may break old
versions of \gpcc, so upgrade gp2c\ at the same time.

However, if you want to compile scripts which do not use the new functions,
you do not need to recompile. Note that you may use the GP environment
variables to tell \path{gp2c-run} which GP to use.
\end{itemize}

\item -t Output the table of types known to the compiler, see
Section~\ref{advanced}.

\end{itemize}

\end{document}