\documentclass[11pt]{article}

\usepackage{makeidx}
\usepackage{url}
\usepackage{syntax}
\usepackage{listings}
\usepackage{amsmath}
\lstset{aboveskip=1.5ex,
        belowskip=1.2ex,
        showstringspaces=false,
        mathescape=true,
        flexiblecolumns=false,
        xleftmargin=2ex,
        basewidth=0.52em,
        basicstyle=\small\ttfamily}
\lstset{literate={->}{{$\rightarrow{}\!\!\!$}}3
       }

% produce an index:
\makeindex
\newcommand{\pindex}[1]{\index{#1@{\tt #1}}}  % program elements in index

\renewcommand{\tt}{\usefont{OT1}{cmtt}{m}{n}\selectfont}
\newcommand{\codefont}{\small\tt}
\newcommand{\code}[1]{\mbox{\codefont #1}}
\newcommand{\ccode}[1]{``\code{#1}''}

% The layout of this manual is adapted from the KiCS2 manual.


%%% ------------------------------------------------------------------

\usepackage[colorlinks,linkcolor=blue]{hyperref}
\hypersetup{bookmarksopen=true}
\hypersetup{bookmarksopenlevel=0}
\hypersetup{pdfstartview=FitH}
\usepackage{thumbpdf}

%%% ------------------------------------------------------------------

\setlength{\textwidth}{16.5cm}
\setlength{\textheight}{23cm}
\renewcommand{\baselinestretch}{1.1}
\setlength{\topmargin}{-1cm}
\setlength{\oddsidemargin}{0cm}
\setlength{\evensidemargin}{0cm}
\setlength{\marginparwidth}{0.0cm}
\setlength{\marginparsep}{0.0cm}

\begin{document}

\title{CPM User's Manual}

\author{Jonas Oberschweiber \qquad Michael Hanus\\[1ex]
{\small Institut f\"ur Informatik, CAU Kiel, Germany}\\[1ex]
{\small\texttt{packages@curry-lang.org}}
}

\maketitle

\tableofcontents

\clearpage


\section{Introduction}

This document describes the Curry package manager (CPM), a tool to
distribute and install Curry libraries and manage version dependencies
between these libraries.

A distinguishing feature of CPM is its ability to perform
\emph{semantic versioning checking}, i.e., CPM provides a command
to check the semantics of a new package version against an
older version of the same package.


\bigskip\bigskip

\section{Installing the Curry Package Manager}

\subsection{Requirements}

CPM requires
\emph{Git}\footnote{\url{http://www.git-scm.com}},
\emph{curl}\footnote{\url{https://curl.haxx.se}},
\emph{tar},
and \emph{unzip} to be available on the \code{PATH} during installation and 
operation.

It is strongly recommended that
SQLite\footnote{\url{https://www.sqlite.org}} is installed
so that the executable \code{sqlite3} is in your path.
In this case, CPM uses a SQLite database for caching
the central package index (see Section~\ref{sec:internals}).
This yields faster response times of various CPM commands.

CPM is part of recent distributions of the Curry systems
PAKCS\footnote{\url{https://www.informatik.uni-kiel.de/~pakcs/}}
(since version 1.15.0)
and
KiCS2\footnote{\url{https://www-ps.informatik.uni-kiel.de/kics2/}}
(since version 0.6.0) so that it can directly be used with
these Curry systems.
If you use an older release of PAKCS or KiCS2 or you want to
install some CPM version from the source repository,
the following section contains some hints about the installation of CPM.

\subsection{Source Code Installation}

To install and use CPM, a working installation of either
PAKCS in version 1.14.1 or greater, or
KiCS2 in version 0.5.1 or greater is required. 
You need to ensure that your Haskell installation reads files
using UTF-8 encoding by default. Haskell uses the system locale charmap for its
default encoding. You can check the current value using 
\code{System.IO.localeEncoding} inside a \code{ghci} session.

To install CPM from the sources, enter the 
root directory of the CPM source distribution.
The main executable \code{curry} of your Curry system must be in your
path (otherwise, you can also specify the root location of your Curry system
by modifying the definition of \code{CURRYROOT} in the \code{Makefile}).
Then type \code{make} to compile CPM which generates
a binary called \code{cypm} in the \code{bin} subdirectory. Put
this binary somewhere on your path.


\clearpage

\section{Starting the Curry Package Manager}

If the binary \code{cypm} is on your path, execute the command
%
\begin{lstlisting}
> cypm update
\end{lstlisting}\pindex{update}
%
to pull down a copy of the central package index to your system.
You can use the same command to update later
your copy of the central package index to the newest version.

Afterwards, you can show a list of all packages in this index by
%
\begin{lstlisting}
> cypm list
\end{lstlisting}\pindex{list}
%
The command
%
\begin{lstlisting}
> cypm info PACKAGE
\end{lstlisting}\pindex{info}
%
can be used to show more information about a package.
There is also a command
%
\begin{lstlisting}
> cypm search QUERY
\end{lstlisting}\pindex{search}
%
to search inside the central package index.

Section~\ref{sec:cmd-reference} contains a complete list of all
available CPM commands.

\clearpage

\section{Package Basics}
\label{sec:package-basics}

Essentially, a Curry package is nothing more than a directory structure 
containing a \code{package.json} file and a \code{src} directory at its root.
The \code{package.json} file is a JSON file containing package metadata, the 
\code{src} directory contains the Curry modules that make up the package.

We assume familiarity with the JSON file format. A good introduction can be 
found at \url{http://json.org}. The package specification file must contain a 
top-level JSON object with at least the keys \code{name}, \code{author}, 
\code{version}, \code{synopsis} and \code{dependencies}. More possible fields 
are described in Section~\ref{sec:reference}. A package's name may contain any
ASCII alphanumeric character as well as dashes (\code{-}) and underscores
(\code{_}). It must start with an alphanumeric character. The author field is a
free-form field, but the suggested format is either a name (\code{John Doe}),
or a name followed by an email address in angle brackets
(\code{John Doe <john.doe@goldenstate.gov>}).
Multiple authors can either be separated by commas or written
as a list of strings.

Versions must be specified in the format laid out in the semantic versioning 
standard:\footnote{\url{http://www.semver.org}}%
\index{version format}\index{semantic versioning}
each version number consists of 
numeric major, minor and patch versions separated by dot characters as well as
an optional pre-release specifier consisting of ASCII alphanumerics and hyphens,
e.g. \code{1.2.3} and \code{1.2.3-beta5}. Please note that build metadata as
specified in the standard is not supported. 

The synopsis should be a short summary of what the package does. Use the 
\code{description} field for longer form explanations. 

Dependencies are specified as a nested JSON object with package names as keys
and dependency constraints as values. A dependency constraint restricts the 
range of versions of the dependency that a package is compatible to. Constraints
consist of elementary comparisons that can be combined into conjunctions, which
can then be combined into one large disjunction---essentially a disjunctive
normal form.
The supported comparison operators are
\code{<}, \code{<=}, \code{>}, \code{>=}, \code{=}, \code{\char126},
and \code{\char94}.
The first five are interpreted according to the rules for comparing
version numbers laid out in the semantic versioning standard.
\code{\char126} requires\footnote{%
In previous versions of CPM this was denoted
as \code{{\char126}>} and called \emph{semantic versioning arrow}.}
that the package version be 
at least as large as its argument but still within the same minor version,
i.e.,
\code{{\char126}1.2.3} would match
\code{1.2.3}, \code{1.2.9}, and \code{1.2.55}
but not \code{1.2.2}, \code{1.3.0}, or \code{2.1.0}.
Analogously, \code{\char94} requires that the package version be 
at least as large as its argument but still within the same major version,
i.e.,
\code{{\char94}1.2.3} would match
\code{1.2.3} and \code{1.4.3}
but not \code{2.1.0}.

To combine multiple comparisons into a conjunction, separate them by commas, 
e.g.,
\begin{lstlisting}
>= 2.0.0, < 3.0.0  
\end{lstlisting}
would match all versions
with major version \code{2}.
Note that it would not match \code{2.1.3-beta5} for example, since pre-release 
versions are only matched if the comparison is explicitly made to a pre-release
version, e.g., \code{= 2.1.3-beta5} or \code{> 2.1.3-beta2}.

Conjunctions can be combined into a disjunction via the
\code{||} characters, e.g.,
\begin{lstlisting}
>= 2.0.0, < 3.0.0 || >= 4.0.0  
\end{lstlisting}
would match any version within major version
\code{2} and from major version \code{4} onwards,
but no version within major version \code{3}.


\clearpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Using Packages}

Curry packages can be used as dependencies of other Curry packages
or to install applications implemented with a package.
In the following we describe both possibilities of using packages.

\subsection{Creating New Packages}

Creating a new Curry package is easy.
To use a Curry package in your project, create a 
\code{package.json}\pindex{package.json}
file in the root, fill it with the minimum amount of 
information discussed in the previous session, and move your Curry code to a
\code{src} directory inside your project's directory.
One can also use the command\pindex{init}
\begin{lstlisting}
cypm init
\end{lstlisting}
to initialize the current directory
with a minimal version of \code{package.json}
and a few other files (like \code{README} or license information).
When starting a new project, one can also use the command\pindex{new}
\begin{lstlisting}
cypm new <project-name>
\end{lstlisting}
to create a new project directory with a 
\code{package.json} file and some other useful template files
(look into the output of this command).
Then declare the dependencies inside the new \code{package.json} file, e.g.:
\pindex{package.json}
\begin{lstlisting}
{
  ...,
  "dependencies": {
    "base": "^1.0.0",
    "html": ">= 2.0.0, < 2.2.0"
    "json": "~1.1.0"
  }
}
\end{lstlisting}
%
Now you can run\pindex{install}
\begin{lstlisting}
cypm install
\end{lstlisting}
to install all dependencies of the current package
and start your interactive Curry environment with the command\pindex{curry}
\begin{lstlisting}
cypm curry
\end{lstlisting}
You will be able to load the JSON package's modules in your Curry session.


\subsection{Installing and Updating Dependencies}

To install the current package's dependencies,
run \code{cypm install}.\pindex{install} This will
install the most recent version of all dependencies that are compatible to the
package's dependency constraints. Note that a subsequent run of 
\code{cypm install} will always prefer the versions it installed on a previous
run, if they are still compatible to the package's dependencies. If you want to
explicitly install the newest compatible version regardless of what was 
installed on previous runs of \code{cypm install}, you can use the 
\code{cypm upgrade}\pindex{upgrade}
command to upgrade all dependencies to their newest 
compatible versions, or \code{cypm upgrade <package>} to update a specific 
package and all its transitive dependencies to the newest compatible version.

If the package also contains an implementation of a complete executable,
e.g., some useful tool,
which can be specifed in the \code{package.json} file
(see Section~\ref{sec:reference}),
then the command \code{cypm install} also compiles the application
and installs the executable in the \code{bin} install directory of CPM
(see Section~\ref{sec:config} for details).
The installation of executables can be suppressed by the
\code{cypm install} option \code{-n} or \code{--noexec}.


\subsection{Checking out Packages}
\label{sec:checkout}

In order to use, experiment with or modify an existing package,
one can use the command\pindex{checkout}
\begin{lstlisting}
cypm checkout <package>
\end{lstlisting}
to install a local copy of a package.
This is also useful to install some tool distributed as a package.
For instance, to install \code{curry-check},
a property-testing tool for Curry,
one can check out the most recent version and install the tool:
%
\begin{lstlisting}
> cypm checkout currycheck
$\ldots$ Package 'currycheck-1.0.1' checked out into directory 'currycheck'.
> cd currycheck
> cypm install
$\ldots$
INFO  Installing executable 'curry-check into '/home/joe/.cpm/bin'
\end{lstlisting}
%
Now, the tool \code{curry-check} is ready to use
if \code{\$HOME/.cpm/bin} is in your path
(see Section~\ref{sec:config} for details about changing the location
of this default path).


\subsection{Installing Applications of Packages}
\label{sec:installapp}

Some packages do not contain only useful libraries
but also application programs or tools.
In order to install the executables of such applications without
explicitly checking out the package in some local directory,
one can use the command\pindex{install}
\begin{lstlisting}
cypm install <package>
\end{lstlisting}
This command checks out the package in some internal directory
(default: \code{\$HOME/.cpm/apps_$Curry system$}, see
Section~\ref{sec:config})
and installs the binary of the application provided by the package
in \code{\$HOME/.cpm/bin} (see also Section~\ref{sec:checkout}).

For instance, the most recent version of the web framework Spicey
can be installed by the following command:
%
\begin{lstlisting}
> cypm install spicey
$\ldots$ Package 'spicey-xxx' checked out $\ldots$
$\ldots$
INFO  Installing executable 'spiceup' into '/home/joe/.cpm/bin'
\end{lstlisting}
%
Now, the binary \code{spiceup} of Spicey can be used
if \code{\$HOME/.cpm/bin} is in your path
(see Section~\ref{sec:config} for details about changing the location
of this default path).


\subsection{Executing the Curry System in a Package}

To use the dependencies of a package, the Curry system needs to be
started via CPM so that it will know where to search for the
modules provided. You can use the command \ccode{cypm curry} to start the
Curry system (which is either the compiler used to install CPM
or specified with the configuration option \code{CURRY_BIN},
see Section~\ref{sec:config}).
Any parameters given to \ccode{cypm curry} will be passed along verbatim to
the Curry system.
For example, the following will start the Curry system,
print the result of evaluating the expression \code{39+3}
and then quit.
\pindex{curry}
\begin{lstlisting}
> cypm curry :eval "39+3" :quit
\end{lstlisting}
%
To execute other Curry commands, such as \ccode{curry check},
with the package's dependencies available,
you can use the \ccode{cypm exec} command.
This command will set the \code{CURRYPATH} environment variable
and then execute the command given after \ccode{exec}.


\subsection{Using Packages Outside a Package}
\label{sec:meta-package}

In principle, packages can be used only inside another package
by declaring dependencies in the package specification file
\code{package.json}.
If you invoke \code{cypm} in a directory which contains
no package specification file, CPM searches for such a file
from the current directory to the parent directories (up to the
root of the file system).
Thus, if you are outside a package, such a file is not available.
In order to support the use other packages outside package,
CPM provides a meta-package which is usually stored in your home directory
at \code{\char126/.cpm/$Curry system$-homepackage}.\footnote{%
Use \code{cypm config} and look at \code{HOME_PACKAGE_PATH}
to see the current location of this meta-package.}
This meta-package is used when your are not inside another package.
Hence, if you write some Curry program which is not a package
but you want to use some package \code{P}, you have to add a dependency
to \code{P} to this meta-package.
CPM does this automatically for you with the CPM command
\code{cypm add --dependency} (short: \code{cypm add -d}).

For instance, to use the libraries of the JSON package
in your application, one can use the following commands:\pindex{add}
%
\begin{lstlisting}
> cypm add -d json  # add 'json' dependency to meta-package
> cypm install      # download and install all dependencies
> cypm curry        # start Curry system with JSON libraries in load path
...
Prelude> :load JSON.Data
JSON.Data>
\end{lstlisting}
%
The default behavior of the \code{add} command is to add the dependency
\emph{and} install all dependencies, i.e., the previous commands
can be reduced as follows:
%
\begin{lstlisting}
> cypm add json
> cypm curry
...
Prelude> :load JSON.Data
JSON.Data>
\end{lstlisting}


\subsection{Replacing Dependencies with Local Versions}
\label{sec:cpm-link}

During development of your applications, situations may arise in which you want
to temporarily replace one of your package's dependencies with a local copy,
without having to publish a copy of that dependency somewhere or increasing the
dependency's version number. One such situation is a bug in a dependency not 
controlled by you: if your own package depends on package $A$ and $A$'s current
version is $1.0.3$ and you encounter a bug in this version, then you might be 
able to investigate, find and fix the bug. Since you are not the the author of
$A$, however, you cannot release a new version with the bug fixed. So you send
off your patch to $A$'s maintainer and wait for $1.0.4$ to be released. In the
meantime, you want to use your local, fixed copy of version $1.0.3$ from your 
package. The \code{cypm link} command allows you to replace a dependency with
your own local copy.

\code{cypm link}\pindex{link}
takes a directory containing a copy of one of the current 
package's dependencies as its argument. It creates a symbolic link from that
directory the the current package's local package cache. If you had a copy of
\code{A-1.0.3} in the \code{\char126/src/A-1.0.3} directory, you could use 
\code{cypm link \char126/src/A-1.0.3} to ensure that any time \code{A-1.0.3} is used 
from the current package, your local copy is used instead of the one from the
global package cache. To remove any links, use \code{cypm upgrade} without any
arguments, which will clear the local package cache. See 
Section~\ref{sec:internals} for more information on the global and local package
caches.

\clearpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Authoring Packages}

If you want to create packages for other people to use, you should consider 
filling out more metadata fields than the bare minimum. See 
Section~\ref{sec:reference} for a reference of all available fields.

\subsection{Semantic Versioning}
\label{sec:semantic-versioning}

The versions of published packages should adhere to the semantic versioning 
standard, which lays out rules for which components of a version number must
change if the public API of a package changes. Recall that a semantic versioning 
version number consists of a major, minor and patch version as well as an 
optional pre-release specifier. In short, semantic versioning defines the 
following rules:

\begin{itemize}
\item If the type of any public API is changed or removed or the expected 
behavior of a public API is changed, you must increase the major version number
and reset the minor and patch version numbers to $0$.

\item If a public API is added, you must increase at least the minor version
number and reset the patch version number to $0$.

\item If only bug fixes are introduced, i.e. nothing is added or removed and
behavior is only changed to removed deviations from the expected behavior, then
it is sufficient to increase the patch version number.

\item Once a version is published, it must not be changed.

\item For pre-releases, sticking to these rules is encouraged but not required.

\item If the major version number is $0$, the package is still considered under
development and thus unstable. In this case, the rules do not apply, although
following them as much as possible as still encouraged. Release $1.0.0$ is 
considered to be the first stable version.
\end{itemize}
%
To aid you in following these rules, CPM provides the \code{diff} command.
\code{diff}\pindex{diff}
can be used to compare the types and behavior of a package's public
API between two versions of that package. If it finds any differences, it checks
whether they are acceptable under semantic versioning for the difference in 
version numbers between the two package versions. To use \code{diff}, you need
to be in the directory of one of the versions, i.e., your copy for development,
and have the other version installed in CPM's global package cache (see the
\code{cypm install} command). For example, if you are developing version $1.3.0$
of the JSON package and want to make sure you have not introduced any breaking
changes when compared to the previous version $1.2.6$, you can use the 
\code{cypm diff 1.2.6} command while in the directory of version $1.3.0$. 

CPM will then check the types of all public functions and data types in all
exported modules of both versions (see the \code{exportedModules} field of the
package specification) and report any differences and whether they violate 
semantic versioning.
CPM will also compare the behavior of all exported functions
in all exported modules whose types have not changed.
Actually, this part is performed by CurryCheck \cite{Hanus16LOPSTR},
a property-based test tool for Curry.
For this purpose, CPM generates a Curry program containing
properties stating the equivalence
of two operations with the same name but defined in two different
versions of a package.
The ideas and scheme of this generation process are
described in \cite{Hanus17ICLP}.
Note that not all functions can be compared via CurryCheck.
In particular, functions taking other functions as arguments
(there are a few other minor restrictions)
can not be checked so that CPM automatically excludes them from checking.

Note that the results of non-terminating operations, like \code{Prelude.repeat},
cannot be compared in a finite amount of time.
To avoid the execution of possibly non-terminating check programs,
CPM compares the behavior of operations
only if it can prove the termination or productivity\footnote{%
An operation is productive if it always produces outermost constructors,
i.e., it cannot run forever without producing constructors.}
of these operations.
Since CPM uses simple criteria to approximate these properties,
there might be operations that are terminating or productive
but CPM cannot show it. In these cases you can use the compiler pragmas
\verb|{-# TERMINATE -#}|\pindex{TERMINATE} or
\verb|{-# PRODUCTIVE -#}|\pindex{PRODUCTIVE} to annotate such
functions. Then CPM will trust these annotations and treat
the annotated operations as terminating or productive, respectively.
For instance, CPM will check the following operation although
it cannot show its termination:

\begin{lstlisting}
{-# TERMINATE -#}
mcCarthy :: Int -> Int
mcCarthy n | n<=100 = mcCarthy (mcCarthy (n+11))
           | n>100 = n-10
\end{lstlisting}
%
As another example, consider the following operation defining
an infinite list:

\begin{lstlisting}
ones :: [Int]
ones = 1 : ones
\end{lstlisting}
%
Although this operation is not terminating, it is productive
since with every step a new constructor is produced.
CPM compares such operations by comparing their results up to
some depth.
On the other hand, the following operation is not classified
as productive by CPM (note that it would not be productive if the
filter condition is changed to \code{(>1)}):

\begin{lstlisting}
{-# PRODUCTIVE -#}
anotherOnes :: [Int]
anotherOnes = filter (>0) ones
\end{lstlisting}
%
Due to the pragma, CPM will compare this operation as other productive
operations.

There might be situations when operations should not be compared,
e.g., if the previous version of the operation was buggy.
In this case, one can mark those functions with the compiler pragma
\verb|{-# NOCOMPARE -#}|\pindex{NOCOMPARE}
so that CPM will not generate tests for them.

Note that there are different ways to state the equivalence of operations
(e.g., see the discussion in \cite{BacciEtAl12}).
CPM offers two kinds of equivalence tests:\index{equivalence}
\begin{itemize}
\item
\emph{Ground equivalence} means that two operations are considered
as equivalent if they yield identical values for identical input values.
\item
\emph{Contextual or full equivalence} means that two operations
are considered as equivalent if they produce the same results
in all possible contexts.
\end{itemize}
%
Since contextual equivalence is more meaningful in the context
of semantic versioning, CPM tests this kind of
equivalence in the default case, based on the techniques
described in \cite{AntoyHanus18FLOPS}.
However, using the option \code{--ground} of the \code{diff} command,
one can also enfore the checking of ground equivalence
as described in \cite{Hanus17ICLP}.


\subsection{Adding Packages to the Central Package Index}
\label{sec:adding-a-package}

When you have your package ready and want to use it in other packages,
it must be added to the central package index so that CPM can find it
when searching for packages. For this purpose, you can use the
\ccode{cypm add} command:
%
\begin{lstlisting}
> cypm add --package mypackage
\end{lstlisting}\pindex{add}
%
In this case, \code{mypackage} is the name of the directory containing
you package. In particular, the JSON file \ccode{mypackage/package.json} must
contain the metadata of the package (see also Section~\ref{sec:reference}).
This command copies your package into your local copy of the central package
index so that it can be used in other packages.
If you want to replace this copy by an improved version
of the same package, you have to provide the option
\code{-f} or \code{--force}.

Note that this command makes your package only available on your local
system. If you want to publish your package so that it can be used
by other CPM users, follow the instruction described next.


\subsection{Testing a Package}
\label{sec:testing-a-package}

Before publishing a package and make it available to other developers
(see Section~\ref{sec:publishing-a-package}), it should be
carefully checked and tested.
For this purpose, CPM offers two commands:
%
\begin{lstlisting}
> cypm check
\end{lstlisting}\pindex{check}
%
This commands checks the current package specification
for consistency of the dependencies.
All source code modules are compiled and their actual imports
are examined. If there is some imported module
which is not part of a package specified in the dependencies,
an error is reported.
If there is some package in the dependency specification
which is not used, a warning is reported.
%
\begin{lstlisting}
> cypm test
\end{lstlisting}\pindex{test}
%
This tests the current package with CurryCheck, i.e.,
all modules are compiled and possible properties contained
in the modules are tested with automatically generated test data.
Moreover, one can also specify test suites.
More details about these commands can be found in
Section~\ref{sec:cmd-reference}.


\subsection{Publishing a Package}
\label{sec:publishing-a-package}

There are three things that need to be done to publish a package: make the
package accessible somewhere, add the location to the package specification, and
add the package specification to the central package index.

CPM supports ZIP (suffix \ccode{.zip}) or
compressed TAR (suffix \ccode{.tar.gz}) files
accessible over HTTP as well as Git repositories as 
package sources. You are free to choose one of those, but a publicly accessible
Git repository is preferred. To add the location to the package specification,
use the \code{source}\pindex{source} key. For a HTTP source, use:
%
\begin{lstlisting}
{
  ...,
  "source": {
    "http": "http://example.com/package-1.0.3.zip"
  }
}
\end{lstlisting}
%
For a Git source, you have to specify both the repository as well as the 
revision that represents the version:
%
\begin{lstlisting}
{
  ...,
  "source": {
    "git": "git+ssh://git@github.com:john-doe/package.git",
    "tag": "v1.2.3"
  }
}
\end{lstlisting}
%
There is also a shorthand, \code{\$version}, available to
automatically use a tag consisting of the letter \code{v} followed by
the current version number, as in the example above. Specifying
\code{\$version} as the tag and then tagging each version in the
format \code{v1.2.3} is preferred, since it does not require changing
the source location in the \code{package.json} file every time a new
version is released.
If one already has a repository with another tagging scheme,
one can also place the string \code{\$version\$}
in the tag, which will be automatically replaced by the current
version number. Thus, the tag \ccode{\$version}\pindex{\$version} is equivalent
to the tag \ccode{v\$version\$}.

After you have published the files for your new package version, you
have to add the corresponding package specification to the central
package index. This can be done with the \ccode{cypm add} command
(see Section~\ref{sec:adding-a-package}).
If you have access to the Git
repository containing the central package index, then you can push
the modified version of this Git repository.
Otherwise, send your package
specification file to \url{packages@curry-lang.org} in order to
publish it.


\clearpage

\section{The \texttt{base} Package}
\label{sec:basepackage}

Every Curry distribution comes with some libraries
to support basic operations, like list operations,
actions to read and write files, etc.
The most prominent library is the \code{Prelude}\pindex{Prelude}
which is implicitly added to the import list of a Curry module.
In order to manage different versions of these base libraries,
there is a distinguished package \code{base}\pindex{base} containing
these libraries.
Thus, one can include a dependency to a specific version
of the \code{base} package in the \code{package.json} file, e.g.:
%
\begin{lstlisting}
{
  ...,
  "dependencies": {
    "base": ">= 2.1.0, < 3.0.0",
    "html": ">= 2.0.0, < 2.2.0"
    "json": "~1.1.0"
  }
  ...
}
\end{lstlisting}
%
Each Curry system comes with a specific version of the \code{base}
package. This version can be queried with the option \code{--base-version},
e.g.,
%
\begin{lstlisting}
> pakcs --base-version
3.0.0
\end{lstlisting}
%
If CPM tries to install a package, it adds the condition
that the version of package \code{base} must be identical to the \code{base}
version of the compiler used by CPM.
For instance, if \code{pakcs} is used by CPM
(see Section~\ref{sec:config} how to change the default compiler of CPM),
the dependencies shown above are changed to
%
\begin{lstlisting}
{
  ...,
  "dependencies": {
    "base": "= 3.0.0, >= 2.1.0, < 3.0.0",
    "html": ">= 2.0.0, < 2.2.0"
    "json": "~1.1.0"
  }
  ...
}
\end{lstlisting}
%
before resolving all constraints.
Of course, in this case, the constraints are not solvable
so that one has to choose another Curry compiler for this package.


\clearpage

\section{Configuration}
\label{sec:config}

CPM can be configured via the \code{\$HOME/.cpmrc} configuration file. The 
following list shows all configuration options and their default values.

\begin{description}
\item[\fbox{\code{CURRY_BIN}}]
The name of the executable of the Curry system used
to compile and test packages.
The default value is the binary of the Curry system which has been used
to compile CPM.

\item[\fbox{\code{REPOSITORY_PATH}}] The path to the index of all packages.
Default value: \code{\$HOME/.cpm/index}.

\item[\fbox{\code{PACKAGE_INSTALL_PATH}}] The path to the global package cache.
This is where all downloaded packages are stored.
Default value: \code{\$HOME/.cpm/packages}

\item[\fbox{\code{BIN_INSTALL_PATH}}] The path to the executables
of packages. This is the location where the compiled executables
of packages containing full applications are stored.
Hence, in order to use such applications, one should have this path
in the personal load path (environment variable \code{PATH}).
Default value: \code{\$HOME/.cpm/bin}

\item[\fbox{\code{APP_PACKAGE_PATH}}]
The path to the package cache where packages are checked out if only
their binaries are installed (see Section~\ref{sec:installapp}).
Default value: \code{\$HOME/.cpm/apps_$Curry system$}.

\item[\fbox{\code{HOME_PACKAGE_PATH}}]
The path to the meta-package which is used if you are outside another
package (see Section~\ref{sec:meta-package}).
Default value: \code{\$HOME/.cpm/$Curry system$-homepackage}.

\item[\fbox{\code{PACKAGE_INDEX_URL}}]
The URL of the central package index
which is used by the \code{update} command to download the
index of all repositories.
Default value:
\begin{lstlisting}
https://cpm.curry-lang.org/PACKAGES/INDEX.tar.gz
\end{lstlisting}
One can also provide more than one URL which are tried in sequential order
until one index could be downloaded.
In this case, the URLs should be separated by a vertical bar (\ccode{|}).

\item[\fbox{\code{PACKAGE_TARFILES_URL}}]
The URL prefix to the directory containing the ``tar'' files of all packages.
If a package $p$ with version $v$ is downloaded
(via the \code{install} or \code{checkout} command),
the source of the package is downloaded from this location
as file \code{$p$-$v$.tar.gz}.
Default value:
\begin{lstlisting}
https://cpm.curry-lang.org/PACKAGES/
\end{lstlisting}
For instance, the package \code{cpm} with version \code{3.1.0}
is downloaded from
\begin{lstlisting}
https://cpm.curry-lang.org/PACKAGES/cpm-3.1.0.tar.gz
\end{lstlisting}
One can also provide more than one URL prefix
which are tried in sequential order until the package could be downloaded
from one of them.
In this case, the URL prefixes should be separated
by a vertical bar (\ccode{|}).

\end{description}
%
The CPM command\pindex{config}
\begin{lstlisting}
> cypm config
\end{lstlisting}
shows the current values of the configuration options.

Note that one write the option names also in lowercase or omit
the underscores. For instance, one can write \code{currybin}
instead of \code{CURRY_BIN}.
Moreover, one can override the values of these configuration options
by the CPM options \code{-d} or \code{--define}.
For instance, to install the binary
of the package \code{spicey} in the directory \code{\$HOME/bin},
one can execute the command
\begin{lstlisting}
> cypm --define bin_install_path=$\$$HOME/bin install spicey
\end{lstlisting}


\clearpage

\section{Some CPM Internals}
\label{sec:internals}

CPM's central package index contains all package specification files.
It is stored at a central server where the actual location is defined
by CPM's configuration variable \code{PACKAGE_INDEX_URL},
see Section~\ref{sec:config}.
When the command
\begin{lstlisting}
> cypm update
\end{lstlisting}
is executed, a copy of this index is downloaded and stored on your
local system in the directory \code{\$HOME/.cpm/index}, unless you
changed the location using the \code{REPOSITORY_PATH} setting. CPM
uses the package index when searching for and installing packages and
during dependency resolution.
This index contains a directory for each package, which contain subdirectories
for all versions of that package which in turn contain the package
specification files. So the specification for version $1.0.5$ of the
\code{json} package would be located in
\code{json/1.0.5/package.json}.  

When a package is installed on the system, it is stored in the
\emph{global package cache}.
By default, the global package cache is located in
\code{\$HOME/.cpm/packages}. When a package \emph{foo}, stored in directory 
\code{foo}, depends on a package \emph{bar}, a link to \emph{bar's} directory in
the global package cache is added to \emph{foo's} local package cache when 
dependencies are resolved for \emph{foo}.
The \emph{local package cache} is stored in 
\code{foo/.cpm/package_cache}. Whenever dependencies are resolved, package 
versions already in the local package cache are preferred over those from the
central package index or the global package cache. 

When a module inside a package is compiled, packages are first copied from the
local package cache to the \emph{run-time cache}, which is stored in 
\code{foo/.cpm/packages}. Ultimately, the Curry compiler only sees the package
copies in the run-time cache, and never those from the local or global package
caches.


\clearpage

\section{Command Reference}
\label{sec:cmd-reference}

This section gives a short description of all available CPM commands.
In addition to the commands listed below, there are some global options
which can be placed in front of the CPM command:
\begin{description}
\item[\code{-d$\,|\,$--define $option$=$value$}:]
This option overrides the configuration options of CPM,
 see Section~\ref{sec:config}.
\item[\code{-v$\,|\,$--verbosity [info|debug]}:]
The default value is \code{info}.
The value \code{debug} provides more output messages in order to see
what CPM is doing.
\item[\code{-t$\,|\,$--time}:]
This option adds the elapsed time to every info or debug output line.
\end{description}
%
The available commands of CPM are:

\begin{description}
\item[\fbox{\code{check}}]\pindex{check}
Checks the current package for consistency of the dependencies
specified in the package specification.
All source code modules are compiled and their actual imports
are examined. If there is some imported module
which is not part of a package specified in the dependencies,
an error is reported.
If there is some package in the dependency specification
which is not used, a warning is reported.
The option \code{--info} shows some more information,
e.g., the complete list of all Curry source modules.

In addition to the interface checks, the static source code
of all package modules are examined by CurryCheck in order to
report unintended uses of some Curry functions,
e.g., set functions or non-strict unification (\code{=:<=}).
The latter checks can be suppressed by the option \code{--source}.

\item[\fbox{\code{config}}]\pindex{config}
Shows the current configuration of CPM
(see also Section~\ref{sec:config}).
The option \code{--all} shows also the names and version
of the packages installed in the global package cache.

\item[\fbox{\code{info}}]\pindex{info}
Gives information on the current package, e.g. the
package's name, author, synopsis and its dependency specifications.

\item[\fbox{\code{info $package$ [--all]}}]\pindex{info}
Prints information on the newest known version (compatible to the
current compiler) of the given package.
The option \code{--all} shows more information.

\item[\fbox{\code{info $package$ $version$ [--all]}}]\pindex{info}
Prints basic information on the given package version.
The option \code{--all} shows more information.

\item[\fbox{\code{list [--system] [--versions] [--csv]}}]\pindex{list}
List the names and synopses of all packages of the central package index.
Unless the option \code{--versions} is set, only the newest version
of a package is shown.
The option \code{--system} restricts the list to those packages
which are compatible with the current compiler (if it is
explicitly specified in the package).
The option \code{--versions} shows all versions of the packages.
If a package is not compatible to the current compiler, then
the package version is shown in brackets (e.g., \ccode{(1.5.4)}).
The option \code{--csv} shows the information in CSV format.

\item[\fbox{\code{list --category [--csv]}}]\pindex{list}
List the category names together with the packages belonging to this
category (see Section~\ref{sec:reference})
of the central package index.
The option \code{--csv} shows the information in CSV format.

\item[\fbox{\code{search [--module|--exec] $query$}}]\pindex{search}
Searches the names, synopses, and exported module names of all 
packages of the central package index for occurrences of the given
search term.
If the option \code{--module} is set, then the given name
is searched in the list of exported modules.
Thus, the package
exporting the module \code{JSON.Data} can be found by the command
%
\begin{lstlisting}
> cypm search --module JSON.Data
\end{lstlisting}
%
If the option \code{--exec} is set, then the search is restricted
to the name of the executable provided by the package.
For instance, the command
%
\begin{lstlisting}
> cypm search --exec show
\end{lstlisting}
%
lists all packages where the name of the executable contains the
string \ccode{show}.

\item[\fbox{\code{update}}]\pindex{update}
Updates the local copy of the central package index
to the newest available version.
This command also cleans the global package cache in order to support
the download of fresh package versions.
Note that this also removes local copies of packages
installed by the command \ccode{add --package}.
The option \code{--url} allows to specify a different URL
for the central package index (might be useful for experimental purposes).

\item[\fbox{\code{install}}]\pindex{install}
Installs all dependencies of the current package.
Furthermore, if the current package contains also executables
for an application,
the executables specified in the package are compiled and installed
(unless the option \code{-n} or \code{--noexec} is set).
With the option \code{-x} or \code{--exec}, the executables
are installed without installing all dependencies again.
This is useful to speed up the re-installation of a previously
installed application.
If a name is added to the option \code{-x} or \code{--exec}, e.g.,
%
\begin{lstlisting}
> cypm install --exec compiler
\end{lstlisting}
%
then only the executable with this name is installed.

\item[\fbox{\code{install $package$ [--$pre$]}}]\pindex{install}
Installs the application provided by the newest version
(compatible to the current compiler) of a package.
The binary of the application is installed into the directory
\code{\$HOME/.cpm/bin}
(this location can be changed via the \code{\$HOME/.cpmrc} configuration file
or by the CPM option \code{--define}, see Section~\ref{sec:config}).
\code{--$pre$} enables the installation of pre-release versions.

\item[\fbox{\code{install $package$ $version$}}]\pindex{install}
Installs the application provided by a specific version of a package.
The binary of the application is installed into the directory
\code{\$HOME/.cpm/bin}
(this location can be changed via the \code{\$HOME/.cpmrc} configuration file
or by the CPM option \code{--define}, see Section~\ref{sec:config}).

\item[\fbox{\code{install $package$.zip}}]\pindex{install}
Installs a package from a ZIP file
to the global package cache. The ZIP file must contain at least the
package description file \code{package.json} and the directory \code{src}
containing the Curry source files.

\item[\fbox{\code{uninstall}}]\pindex{uninstall}
Uninstalls the executable installed for the current package.

\item[\fbox{\code{uninstall $package$}}]\pindex{uninstall}
Uninstalls the executable and the cached copy of a package
which has been installed by the \code{install} command.

\item[\fbox{\code{uninstall $package$ $version$}}]\pindex{uninstall}
Uninstalls a specific version
of a package from the global package cache.

\item[\fbox{\code{checkout $package$ [--$pre$]}}]\pindex{checkout}
Checks out the newest version (compatible to the current compiler)
of a package into the local directory \code{$package$}
in order to test its operations or install a binary of the package.
\code{--$pre$} enables the installation of pre-release versions.

\item[\fbox{\code{checkout $package$ $version$}}]\pindex{checkout}
Checks out a specific version of a package
into the local directory \code{$package$}
in order to test its operations or install a binary of the package..

\item[\fbox{\code{upgrade}}]\pindex{upgrade}
Upgrades all dependencies of the current package to
the newest compatible version.

\item[\fbox{\code{upgrade $package$}}]\pindex{upgrade}
Upgrades a specific dependency of the
current package and all its transitive dependencies to their newest compatible
versions.

\item[\fbox{\code{deps}}]\pindex{deps}
Does a dependency resolution run for the current 
package and prints the results. The result is either a list of all package
versions chosen or a description of the conflict encountered during dependency
resolution.
In order to reduce the amount of information shown,
only the first occurrence of a package is shown.
If the option \code{--full} is given, then also repeated package
dependencies are shown.

If the option \code{--path} is set, only the value of \code{CURRYPATH}
required to load modules of this package is shown.

If the option \code{--language-server} is set, the full path containing
all source directories is written into the file
in the file \ccode{.curry/language-server/paths.json}.
This file is used by the Curry Language Server%
\footnote{\url{https://github.com/fwcd/curry-language-server}}
to find all imported modules of the current package
when it is used in the VS Code source-code editor.
When starting the Curry Language Server with VS Code,
the language server invokes CPM with this option in order to
set its import path.

For older version of the Curry Language Server,
one can also use the option \code{--code} to set the full path
of all source directories as property
\code{curry.languageServer.importPaths}
in the file \ccode{.vscode/settings.json}
(which is updated if it already exists).

If the option \code{--graph} is provided, then the dependency
graph is translated into a graph in
GraphViz\footnote{\url{http://www.graphviz.org/}} format.
With the option \code{--viewgraph}, the dependency graph is visualized
with the command defined in the \code{dotviewcommand} field of the
rc file of the Curry system (e.g., \code{~/.pakcsrc} in case of PAKCS).

\item[\fbox{\code{test [--modules $\mathit{modules}$] [--compile]}}]\pindex{test}
Tests the current package with CurryCheck.
If the package specification contains a definition of a test suite
(entry \code{testsuite}, see Section~\ref{sec:reference}),
then the modules defined there are tested.
If there is no test suite defined,
the list of exported modules are tested,
if they are explicitly specified
(field \code{exportedModules} of the package specification),
otherwise all modules in the directory \code{src}
(including hierarchical modules stored in its subdirectories) are tested.
Using the option \code{--modules}, one can also specify a comma-separated
list of module names to be tested.

If the executable \code{curry-check} is not installed or the
option \code{--compile} is provided, then the modules are only compiled
and not tested.
Hence, a package can be checked for compilation errors
by the command
\begin{lstlisting}
cypm test --compile
\end{lstlisting}

\item[\fbox{\code{doc}}]\pindex{doc}
Generates the documentation of the current package.
The documentation consists of the API documentation (in HTML format)
and the manual (if provided) in PDF format.
The options \code{--programs} and \code{--text} forces to generate
only the API documentation and the manual, respectively.
Using the option \code{--docdir}, one can specify the
target directory where the documentation should be stored.
If this option is not provided, \ccode{cdoc} is used as the documentation
directory.
The actual documentation will be stored in the subdirectory
\code{$name$-$version$} of the documentation directory.

The API documentation in HTML format is generated with CurryDoc.
If the package specification contains a list of exported modules
(see Section~\ref{sec:reference}),
then these modules are documented.
Otherwise, the main module (if the package specification contains
the entry \code{executable}, see Section~\ref{sec:reference})
or all modules in the directory \code{src}
(including hierarchical modules stored in its subdirectories)
are documented.
Using the option \code{--modules}, one can also specify a comma-separated
list of module names to be documented.

In the default case, modules contained in packages used by the current package
are not documented. Instead, it is assumed that these packages are
already documented\footnote{See
\url{https://cpm.curry-lang.org/DOC/}
for the documentation of all packages. This default location
can be changed with the option \code{--url}.}
so that links to these package documentations are generated.
Using the option \code{--full}, one can generate also the documentation
of packages used by the current package. This might be reasonable
if one uses packages which are only locally installed.

The manual is generated only if the package specification contains
a field \code{documentation} where the main file of the manual
is specified (see Section~\ref{sec:reference} for more details).

\item[\fbox{\code{diff [$version$]}}]\pindex{diff}
Compares the API and behavior of the current package to another
version of the same package.
If the version option is missing, the latest version of the current package
found in the repository is used for comparison.
If the options \code{--api-only} or \code{--behavior-only} are added,
then only the API or the behavior are compared, respectively.
In the default case, all modules commonly exported by both
versions of the package are compared.
Using the option \code{--modules}, one can restrict this comparison
to a list of modules specified by a comma-separated list of module names.

As described in Section~\ref{sec:semantic-versioning},
CPM uses property tests to compare the behavior
of different package versions. In order to avoid
infinite loops durings these tests, CPM analyzes the termination
behavior of the involved operations.
Using the operation \code{--unsafe}, CPM omits this program analysis
but then you have to ensure that all operations are terminating
(or you can annotate them by pragmas,
see Section~\ref{sec:semantic-versioning}).

In the default case, CPM tests the contextual equivalence of
operations (see Section~\ref{sec:semantic-versioning}).
With the option \code{--ground}, the ground equivalence of operations
is tested.


\item[\fbox{\code{exec $command$}}]\pindex{exec}
Executes an arbitrary command with the 
\code{CURRYPATH} environment variable set to the paths of all dependencies of
the current package.
For example, it can be used to execute \ccode{curry check}
or \ccode{curry analyze} with correct dependencies available.

\item[\fbox{\code{curry $args$}}]\pindex{curry}
Executes the Curry compiler with the 
dependencies of the current package available.
Any arguments are passed verbatim to the compiler.

\item[\fbox{\code{link $source$}}]\pindex{link}
Can be used to replace a dependency of the 
current package using a local copy, see Section~\ref{sec:cpm-link} for details.

\item[\fbox{\code{add --package $dir$ [--force]}}]\pindex{add}
Copies the package contained in directory $dir$ into the local copy
of the central package index so that it can be used by other packages
in the local environment
(see Section~\ref{sec:adding-a-package} for details).
The option \ccode{--force} allows to overwrite existing copies
in the central package index.

\item[\fbox{\code{add --dependency $package$ [--force]}}]\pindex{add}
Adds the package $package$ as a new dependency.
This command adds a dependency to the given package
either in the package description file (\code{package.json})
of the current package or in the meta-package
(see Section~\ref{sec:meta-package}).
The option \ccode{--force} allows to overwrite existing dependencies
in the package description file.

\item[\fbox{\code{add $package$ [--force]}}]\pindex{add}
Adds the package $package$ as a new dependency and install
the new dependencies. Thus, this abbreviates the two commands
\begin{lstlisting}
cypm add $package$ && cypm install
\end{lstlisting}

\item[\fbox{\code{clean [--dependencies]}}]\pindex{clean}
Cleans the current package from the
generated auxiliary files, e.g., intermediate Curry files,
installed dependent packages, etc.
Note that a binary installed in the CPM \code{bin} directory
(by the \code{install} command) will not be removed.
For instance, this command can be used to clean an application package
after installing the application.

If the option \code{-d} or \code{--dependencies} is provided,
then \emph{all} dependencies in the package specification are removed.
This might be reasonable in the ``homepackage'' to remove
locally installed packages.

\item[\fbox{\code{new $project$}}]\pindex{new}
Creates a new project package with the given name and some template files
in the directory $project$.

\item[\fbox{\code{init}}]\pindex{init}
Initializes a new project package in the current directory
and puts some template files in this directory.
The name of the new package is the same as the directory name.

\item[\fbox{\code{upload [--tag] [--nopublish] [--force] [--login $name$] [--password $passwd$]}}]\pindex{upload}
Uploads the current package to the central package index managed by
Masala.\index{Masala}%
\footnote{See \url{https://cpm.curry-lang.org/masala/}}
Thus, one has to be registered to Masala (see Masala's homepage
for further information).
Registration is free but only trusted users or the Masala administrator
can publish the package so that it can be used by other developers via CPM
(after updating their local copy of the central package index
by \ccode{cypm update}).
Uploading requires that the package has a public source location, e.g.,
%
\begin{lstlisting}
{
  ...,
  "source": {
    "git": "https://github.com/curry-packages/$\ldots$.git",
    "tag": "$\$$version"
  }
}
\end{lstlisting}
%
Thus, the uploaded package will be taken from this public source
and \textbf{not from the local files}.

If the source location is a git repository with tag
\ccode{$\$$version} (as shown above) and the upload option \code{--tag} is set,
the version tag wil be automatically set in the local repository
(and pushed to the remote repository, i.e., one should have write access
to the remote repository).
If the option \code{--tag} is not provided, the user will be asked
whether the repository should be tagged (if it is a git repository).

Before uploading the package to Masala,
the remote repository will be cloned and tested (by \ccode{cypm test}).
If this is successful, the package specification of the repository
will be added to the central package index (by a web service
of the central package index) and then published
(unless the option \ccode{--nopublish} is set or the user is not
a trusted Masala user).

One can also use the options \code{--login} and \code{--password}
to provide the login name and password of Masala at the command line.
Otherwise, one will be asked for this information after the
package has been successfully tested.

Users registered with administrator rights at Masala can also
use the option \ccode{--force} to overwrite
an existing version in the central package index.

\end{description}


\clearpage

\section{Package Specification Reference}
\label{sec:reference}

This section describes all metadata fields available in a CPM package 
specification. Mandatory fields are marked with a \code{*} character.

\begin{description}
\item[\fbox{\code{name*}}]\pindex{name}
The name of the package. Must only contain ASCII 
letters, digits, hyphens and underscores. Must start with a letter.

\item[\fbox{\code{version*}}]\pindex{version}
The version of the package. Must follow the format
for semantic versioning version numbers.

\item[\fbox{\code{author*}}]\pindex{author}
The package's author. This is a free-form field, 
the suggested format is either a name or a name followed by an email address in
angle brackets, e.g.,
\begin{lstlisting}
John Doe <john@doe.com>
\end{lstlisting}
Multiple authors can either be separated by commas or written
as a list of strings.

\item[\fbox{\code{maintainer}}]\pindex{maintainer}
The current maintainers of the package, if 
different from the original authors. This field allows the current maintainers
to indicate the best person or persons to contact about the package while 
attributing the original authors.

The suggested format is similarly to the authors,
i.e., a name followed by an email address in angle brackets, e.g.,
\begin{lstlisting}
John Doe <john@doe.com>
\end{lstlisting}
Multiple maintainers can either be separated by commas or written
as a list of strings.

\item[\fbox{\code{synopsis*}}]\pindex{synopsis}
A short form summary of the package's purpose.
It should be kept as short as possible (ideally, less than 100 characters).

\item[\fbox{\code{description}}]\pindex{description}
A longer form description of what the package does.

\item[\fbox{\code{category}}]\pindex{category}
A list of keywords that characterize the main area where the
package can be used, e.g., \code{Data}, \code{Numeric}, \code{GUI},
\code{Web}, etc.

\item[\fbox{\code{license}}]\pindex{license}
The license under which the package is distributed.
This is a free-form field. In case of a well-known license such as the GNU 
General Public License\footnote{\url{https://www.gnu.org/licenses/gpl-3.0.en.html}},
the SPDX license identifier\footnote{\url{https://spdx.org/licenses/}} should be 
specified. If a custom license is used, this field should be left blank in favor
of the license file field.

\item[\fbox{\code{licenseFile}}]\pindex{licenseFile}
The name of a file in the root directory of the
package containing explanations regarding the license of the package or the full
text of the license. The suggested name for this file is \code{LICENSE}.

\item[\fbox{\code{copyright}}]\pindex{copyright}
Copyright information regarding the package.

\item[\fbox{\code{homepage}}]\pindex{homepage}
The package's web site. This field should contain a valid URL.

\item[\fbox{\code{bugReports}}]\pindex{bugReports}
A place to report bugs found in the package.
The suggested formats are either a valid URL to a bug tracker
or an email address.

\item[\fbox{\code{repository}}]\pindex{repository}
The location of a SCM repository containing the package's source
code. Should be a valid URL to either a repository (e.g. a Git URL),
or a website representing the repository.

\item[\fbox{\code{dependencies*}}]\pindex{dependencies}
The package's dependencies. This must be JSON
object where the keys are package names and the values are version 
constraints. See Section~\ref{sec:package-basics} for more details.

\item[\fbox{\code{compilerCompatibility}}]\pindex{compilerCompatibility}
The package's compatibility to 
different Curry compilers. Expects a JSON object where the keys are compiler 
names and the values are version constraints. Currently, the supported compiler
names are \code{pakcs} and \code{kics2}. If this field is missing or contains
an empty JSON object, the package is assumed to be compatible to all compilers
in all versions.

The compiler compatibility of a package is also relevant when
some version of a package should be examined or installed
(with CPM commands \code{info}, \code{checkout}, \code{install}).
If a newest package should be installed, i.e., no specific version
number is provided, then only the newest version
which is compatible to the current Curry compiler
(see also Section~\ref{sec:config} for configuration option \code{CURRY_BIN})
is considered.
Similarly, the current package is executed
(CPM commands \code{curry} and \code{test})
only if the current Curry compiler is compatible to this package.

\item[\fbox{\code{source}}]\pindex{source}
A JSON object specifying where the version of the
package described in the specification can be obtained. See 
Section~\ref{sec:publishing-a-package} for details.

\item[\fbox{\code{sourceDirs}}]\pindex{sourceDirs}
A list of directories inside this
package where the source code is located.
When the package is compiled, these directories are put at the front
of the Curry load path.
If this field is not specified, \code{src} is used as the single
source directory.

\item[\fbox{\code{exportedModules}}]\pindex{exportedModules}
A list of modules intended for use by 
consumers of the package.
These are the modules compared by the \code{cypm diff}
command (and tested by the \code{cypm test} command if a list of
test modules is not provided).
Note that modules not in this list are still accessible to consumers
of the package.

\item[\fbox{\code{configModule}}]\pindex{configModule}
A module name into which some information about the package configuration
(location of the package directory, name of the executable, see below)
is written when the package is installed.
This could be useful if the package needs some data files
stored in this package during run time.
For instance, a possible specification could be as follows:
%
\begin{lstlisting}
{
  ...,
  "configModule": "CPM.PackageConfig",
  ...
}
\end{lstlisting}
%
In this case, the package configuration is written into the Curry
file \code{src/CPM/PackageConfig.curry}.

\item[\fbox{\code{executable}}]\pindex{executable}
A JSON object specifying the name of the executable and the main module
if this package contains also an executable application.
The name of the executable must be defined (with key \code{name})
whereas the name of the main module (key \code{main}) is optional.
If the latter is missing, CPM assumes that the main module is \code{Main}.
Furthermore, the executable specification can also contain
options for various Curry compilers. The options must be a JSON object
consisting of compiler names as keys and an option string for the compiler.
For instance, a possible specification could be as follows:
%
\begin{lstlisting}
{
  ...,
  "executable": {
    "name": "cypm",
    "main": "CPM.Main",
    "options": { "kics2" : ":set rts -T" }
   }
}
\end{lstlisting}
%
If a package contains an \code{executable} specification,
the command \code{cypm install} also compiles the main module
and installs the executable in the \code{bin} install directory of CPM
(see Section~\ref{sec:config} for details).

\item[\fbox{\code{executables}}]\pindex{executables}
It is also possible to specify more than one executable
in package which will be installed by the command \code{cypm install}.
In this case, one can use \code{executables}
instead of \code{executable}.
The value of \code{executables} is an array of JSON objects as used
as \code{executable} values.
For instance, a possible specification could be
%
\begin{lstlisting}
{
  ...,
  "executables": [ {
                   "name": "compiler",
                   "main": "Compiler.Main"
                   },
                   {
                   "name": "repl",
                   "main": "REPL.Main"
                   }
                 ]
}
\end{lstlisting}

\item[\fbox{\code{testsuite}}]\pindex{testsuite}
A JSON object specifying a test suite for this package.
This object contains a directory (with key \code{src-dir})
in which the tests are executed.
Furthermore, the test suite must also define a list of
modules to be tested (with key \code{modules}).
For instance, a possible test suite specification could be as follows:
%
\begin{lstlisting}
{
  ...,
  "testsuite": {
    "src-dir": "test",
    "modules": [ "testDataConversion", "testIO" ]
  }
}
\end{lstlisting}
%
All these modules are tested with CurryCheck
by the command \code{cypm test}.
If no test suite is defined, all (exported) modules are tested
in the directory \code{src}.
A test suite can also contain a field \code{options}
which defines a string of options passed to the call to CurryCheck.

If a test suite contains a specific test script instead
modules to be tested with CurryCheck, then one can specify the name
of this test script in the field \code{script}.
In this case, this script is executed in the test directory
(with the possible \code{options} value added).
The script should return the exit code \code{0} if the test is
successful, otherwise a non-zero exit code.
Note that one has to specify either a (non-empty) list of modules
or a test script name in a test suite, but not both.

One can also specify several test suites for a package.
In this case, the \code{testsuite} value is an array
of JSON objects as described above.
For instance, a test suite specification for tests in the
directories \code{test} and \code{examples} could be as follows:
%
\begin{lstlisting}
{
  ...,
  "testsuite": [
     { "src-dir": "test",
       "options": "-v",
       "script": "test.sh"
     },
     { "src-dir": "examples",
       "options": "-m80",
       "modules": [ "Nats", "Ints" ]
     }
  ]
}
\end{lstlisting}

\item[\fbox{\code{documentation}}]\pindex{documentation}
A JSON object specifying the name of the directory
which contains the sources of the documentation (e.g., a manual)
of the package, the main file of the documentation, and an optional command
to generate the documentation.
For instance, a possible specification could be as follows:
%
\begin{lstlisting}
{
  ...,
  "documentation": {
    "src-dir": "docs",
    "main"   : "manual.tex",
    "command": "pdflatex -output-directory=OUTDIR manual.tex"
  }
  ...
}
\end{lstlisting}
%
In this case, the directory \code{docs} contains the sources of
the manual and \code{manual.tex} is its main file which will be
processed with the specified command.
Occurrences of the string \code{OUTDIR} in the command string
will be replaced by the actual documentation directory
(see description of the command \code{cypm doc}).
If the command is omitted, the following commands are used
(and you have to ensure that these programs are installed):
\begin{itemize}
\item
If the main file has the extension \code{.tex},
e.g., \code{manual.tex}, the command is
\begin{lstlisting}
pdflatex -output-directory=OUTDIR manual.tex
\end{lstlisting}
and it will be executed twice.
\item
If the main file has the extension \code{.md},
e.g., \code{manual.md}, the command is
\begin{lstlisting}
pandoc manual.md -o OUTDIR/manual.pdf
\end{lstlisting}
\end{itemize}

\end{description}
%
In order to get a compact overview over all metadata fields,
we show an example of a package specification where all fields
are used:
%
\begin{lstlisting}
{
    "name": "PACKAGE_NAME",
    "version": "0.0.1",
    "author": "YOUR NAME <YOUR EMAIL ADDRESS>",
    "maintainer": [ "ANOTHER NAME <ANOTHER EMAIL ADDRESS>",
                    "FURTHER NAME <FURTHER EMAIL ADDRESS>" ],
    "synopsis": "A ONE-LINE SUMMARY ABOUT THE PACKAGE",
    "description": "A MORE DETAILED SUMMARY ABOUT THE PACKAGE",
    "category": [ "Category1", "Category2" ],
    "license": "BSD-3-Clause",
    "licenseFile": "LICENSE",
    "copyright": "COPYRIGHT INFORMATION",
    "homepage": "THE URL OF THE WEB SITE OF THE PACKAGE",
    "bugReports": "EMAIL OR BUG TRACKER URL FOR REPORTING BUGS",
    "repository": "THE (GIT) URL OF THE WEB SITE REPOSITORY",
    "dependencies": {
        "PACKAGE1" : ">= 0.0.1, < 1.5.0",
        "PACKAGE2" : "~1.2.3",
        "PACKAGE3" : ">= 2.1.4, < 3.0.0 || >= 4.0.0",
        "PACKAGE2" : "^2.1.3",
    },
    "compilerCompatibility": {
        "pakcs": ">= 1.14.0, < 2.0.0",
        "kics2": ">= 0.5.0, < 2.0.0"
    },
    "sourceDirs" : [ "src", "include" ],
    "exportedModules": [ "Module1", "Module2" ],
    "configModule": "ConfigPackage",
    "executable": {
        "name": "NAME_OF_BINARY",
        "main": "Main",
        "options": {
            "kics2" : ":set rts -T",
            "pakcs" : ":set printdepth 100"
        }
    },
    "testsuite": [
       { "src-dir": "src",
         "options": "-m80",
         "modules": [ "Module1", "Module2" ]
       },
       { "src-dir": "examples",
         "options": "-v",
         "script" : "test.sh"
       }
    ],
    "documentation": {
        "src-dir": "docs",
        "main"   : "manual.tex",
        "command": "pdflatex -output-directory=OUTDIR manual.tex"
    },
    "source": {
        "git": "URL OF THE GIT REPOSITORY",
        "tag": "$\$$version"
    }
}
\end{lstlisting}


\clearpage

\section{Error Recovery}
\label{sec:recovery}

There might occur situations when your package or repository
is in an inconsistent state, e.g., when you manually changed
some internal files or such files have been inadvertently changed or
deleted, or a package is broken due to an incomplete download.
Since CPM checks these files, CPM might exit with an error message
that something is wrong.
In such cases, it might be a good idea to clean up your package file system.
Here are some suggestions how to do this:
\begin{description}
\item[\code{cypm clean}]~\\
This command cleans the current package from
generated auxiliary files (see Section~\ref{sec:cmd-reference}).
Then you can re-install the package and packages on which it depends
by the command \code{cypm install}.
\item[\code{rm -rf \$HOME/.cpm/packages}] ~\\
This cleans all packages which have been previously installed
in the global package cache (see Section~\ref{sec:internals}).
Such an action might be reasonable in case of some download failure.
After clearing the global package cache, all necessary packages
are downloaded again when they are needed.
\item[\code{rm -rf \$HOME/.cpm/index}] ~\\
This removes the central package index of CPM
(see Section~\ref{sec:internals}).
You can simply re-install the newest version of this index
by the command \code{cypm update}.
\end{description}

\newpage
\begin{thebibliography}{1}

\bibitem{AntoyHanus18FLOPS}
S.~Antoy and M.~Hanus.
\newblock Equivalence Checking of Non-deterministic Operations.
\newblock In {\em Proc. of the 14th International Symposium on Functional and
  Logic Programming (FLOPS 2018)}, pp. 149--165. Springer LNCS 10818, 2018.

\bibitem{BacciEtAl12}
G.~Bacci, M.~Comini, M.A. Feli{\'u}, and A.~Villanueva.
\newblock Automatic Synthesis of Specifications for First Order {Curry}.
\newblock In {\em Principles and Practice of Declarative Programming
  (PPDP'12)}, pp. 25--34. ACM Press, 2012.

\bibitem{Hanus16LOPSTR}
M.~Hanus.
\newblock {CurryCheck}: Checking Properties of {Curry} Programs.
\newblock In {\em Proceedings of the 26th International Symposium on
  Logic-Based Program Synthesis and Transformation (LOPSTR 2016)}, pp.
  222--239. Springer LNCS 10184, 2017.

\bibitem{Hanus17ICLP}
M.~Hanus.
\newblock Semantic Versioning Checking in a Declarative Package Manager.
\newblock In {\em Technical Communications of the 33rd International Conference
  on Logic Programming (ICLP 2017)}, OpenAccess Series in Informatics (OASIcs),
  pp. 6:1--6:16. Schloss Dagstuhl - Leibniz-Zentrum fuer Informatik, 2017.

\end{thebibliography}

\newpage
\addcontentsline{toc}{section}{Index}
\printindex

\end{document}

%  LocalWords:  CPM versioning
