manual.tex 53.7 KB
Newer Older
Michael Hanus's avatar
Michael Hanus committed
1
2
3
4
5
6
7
\documentclass[11pt]{article}

\usepackage{url}
\usepackage{syntax}
\usepackage{listings}
\usepackage{amsmath}
\lstset{aboveskip=1.5ex,
Michael Hanus's avatar
Michael Hanus committed
8
        belowskip=1.2ex,
Michael Hanus's avatar
Michael Hanus committed
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
        showstringspaces=false,
        mathescape=true,
        flexiblecolumns=false,
        xleftmargin=2ex,
        basewidth=0.52em,
        basicstyle=\small\ttfamily}
\lstset{literate={->}{{$\rightarrow{}\!\!\!$}}3
       }
\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-language.org}}
}

\maketitle

Michael Hanus's avatar
Michael Hanus committed
55
56
57
58
59
60
61
\tableofcontents

\clearpage


\section{Introduction}

Michael Hanus's avatar
Michael Hanus committed
62
63
64
This document describes the Curry package manager (CPM), a tool to
distribute and install Curry libraries and manage version dependencies
between these libraries.
Michael Hanus's avatar
Michael Hanus committed
65
66
67
68
69
70
71
72

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
Michael Hanus's avatar
Michael Hanus committed
73
74
75

\section{Installing the Curry Package Manager}

Michael Hanus's avatar
Michael Hanus committed
76
CPM is part of recent distributions of the Curry systems
Michael Hanus's avatar
Michael Hanus committed
77
PAKCS\footnote{\url{https://www.informatik.uni-kiel.de/~pakcs/}}
Michael Hanus's avatar
Michael Hanus committed
78
79
(since version 1.15.0)
and
Michael Hanus's avatar
Michael Hanus committed
80
KiCS2\footnote{\url{https://www-ps.informatik.uni-kiel.de/kics2/}}
Michael Hanus's avatar
Michael Hanus committed
81
82
83
84
85
86
87
88
(since version 0.6.0).
If you use an older release of PAKCS or KiCS2 or you want to
install the most recent CPM version from the source repository,
this section contains some hints about the installation of CPM.

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. Additionally, CPM requires 
Michael Hanus's avatar
Michael Hanus committed
89
90
91
92
93
94
95
96
\emph{Git}\footnote{\url{http://www.git-scm.com}},
\emph{curl}\footnote{\url{https://curl.haxx.se}}
and \emph{unzip} to be available on the \code{PATH} during installation and 
operation. You also need to ensure that your Haskell installations 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.

Michael Hanus's avatar
Michael Hanus committed
97
98
99
100
101
102
103
It is also 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.

Michael Hanus's avatar
Michael Hanus committed
104
105
106
107
108
109
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
Michael Hanus's avatar
Michael Hanus committed
110
a binary called \code{cypm} in the \code{bin} subdirectory. Put
Michael Hanus's avatar
Michael Hanus committed
111
112
this binary somewhere on your path.

Michael Hanus's avatar
Michael Hanus committed
113
114
115
116
117

\clearpage

\section{Starting the Curry Package Manager}

Michael Hanus's avatar
Michael Hanus committed
118
If the binary \code{cypm} is on your path, execute the command
Michael Hanus's avatar
Michael Hanus committed
119
120
%
\begin{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
121
> cypm update
Michael Hanus's avatar
Michael Hanus committed
122
123
124
125
126
127
128
129
130
\end{lstlisting}
%
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 short list of all packages in this index by
%
\begin{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
131
> cypm list
Michael Hanus's avatar
Michael Hanus committed
132
133
134
135
136
\end{lstlisting}
%
The command
%
\begin{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
137
> cypm info PACKAGE
Michael Hanus's avatar
Michael Hanus committed
138
139
140
141
142
143
\end{lstlisting}
%
can be used to show more information about a package.
There is also a command
%
\begin{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
144
> cypm search QUERY
Michael Hanus's avatar
Michael Hanus committed
145
146
147
148
149
150
151
152
\end{lstlisting}
%
to search inside the central package index.

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

\clearpage
Michael Hanus's avatar
Michael Hanus committed
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207

\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>}). Separate multiple authors with
commas. 

Versions must be specified in the format laid out in the semantic versioning 
standard:\footnote{\url{http://www.semver.org}} 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 $<, \leq, >, \geq, =$ and 
$\sim>$. The first four are interpreted according to the rules for comparing
version numbers laid out in the semantic versioning standard. $\sim>$ is called
the \emph{semantic versioning arrow}. It requires that the package version be 
at least as large as its argument, but still within the same minor version, i.e.
$\sim> 1.2.3$ would match $1.2.3$, $1.2.9$ and $1.2.55$, but not $1.2.2$ or
$1.3.0$.

To combine multiple comparisons into a conjunction, separate them by commas, 
e.g. $\geq 2.0.0, < 3.0.0$ would match all versions with major version $2$. 
Note that it would not match \textit{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. $= \text{2.1.3-beta5}$ or $\geq \text{2.1.3-beta2}$.

Conjunctions can be combined into a disjunction via the $||$ characters, e.g.
$\geq 2.0.0, < 3.0.0 || \geq 4.0.0$ would match any version within major version
$2$ and from major version $4$ onwards, but no version within major version $3$.


Michael Hanus's avatar
Michael Hanus committed
208
209
\clearpage

Michael Hanus's avatar
Michael Hanus committed
210
211
212
213
214
215
216
217
218
219
220
221
222
223
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\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} 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. Alternatively, if you are
Michael Hanus's avatar
Michael Hanus committed
224
starting a new project, use the \code{cypm new <project-name>} command, which 
Michael Hanus's avatar
Michael Hanus committed
225
226
227
228
creates a new project directory with a 
\code{package.json} file for you.\footnote{The \code{new} command
also creates some other useful template files. Look into the
output of this command.}
Michael Hanus's avatar
Michael Hanus committed
229
Then declare the dependencies inside the new \code{package.json} file, e.g.:
Michael Hanus's avatar
Michael Hanus committed
230
231
232
233
234

\begin{lstlisting}
{
  ...,
  "dependencies": {
Michael Hanus's avatar
Michael Hanus committed
235
    "base": ">= 1.0.0, < 2.0.0",
Michael Hanus's avatar
Michael Hanus committed
236
237
238
239
240
    "json": "~> 1.1.0"
  }
}
\end{lstlisting}
%
Michael Hanus's avatar
Michael Hanus committed
241
242
Then run \code{cypm install} to install all dependencies of the current package
and start your interactive Curry environment with \code{cypm curry}. You will be
Michael Hanus's avatar
Michael Hanus committed
243
244
245
246
247
able to load the JSON package's modules in your Curry session.


\subsection{Installing and Updating Dependencies}

Michael Hanus's avatar
Michael Hanus committed
248
To install the current package's dependencies, run \code{cypm install}. This will
Michael Hanus's avatar
Michael Hanus committed
249
250
install the most recent version of all dependencies that are compatible to the
package's dependency constraints. Note that a subsequent run of 
Michael Hanus's avatar
Michael Hanus committed
251
\code{cypm install} will always prefer the versions it installed on a previous
Michael Hanus's avatar
Michael Hanus committed
252
253
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 
Michael Hanus's avatar
Michael Hanus committed
254
255
256
installed on previous runs of \code{cypm install}, you can use the 
\code{cypm upgrade} command to upgrade all dependencies to their newest 
compatible versions, or \code{cypm upgrade <package>} to update a specific 
Michael Hanus's avatar
Michael Hanus committed
257
258
259
260
261
262
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}),
Michael Hanus's avatar
Michael Hanus committed
263
then the command \code{cypm install} also compiles the application
Michael Hanus's avatar
Michael Hanus committed
264
265
and installs the executable in the \code{bin} install directory of CPM
(see Section~\ref{sec:config} for details).
Michael Hanus's avatar
Michael Hanus committed
266
The installation of executables can be suppressed by the
Michael Hanus's avatar
Michael Hanus committed
267
\code{cypm install} option \code{-n} or \code{--noexec}.
Michael Hanus's avatar
Michael Hanus committed
268
269
270
271
272
273
274
275


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

In order to use, experiment with or modify an existing package,
one can use the command
\begin{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
276
cypm checkout <package>
Michael Hanus's avatar
Michael Hanus committed
277
278
279
\end{lstlisting}
to install a local copy of a package.
This is also useful to install some tool distributed as a package.
Michael Hanus's avatar
Michael Hanus committed
280
281
For instance, to install \code{curry-check},
a property-testing tool for Curry,
Michael Hanus's avatar
Michael Hanus committed
282
283
284
one can check out the most recent version and install the tool:
%
\begin{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
285
> cypm checkout currycheck
Michael Hanus's avatar
Michael Hanus committed
286
287
$\ldots$ Package 'currycheck-1.0.1' checked out into directory 'currycheck'.
> cd currycheck
Michael Hanus's avatar
Michael Hanus committed
288
> cypm install
Michael Hanus's avatar
Michael Hanus committed
289
$\ldots$
Michael Hanus's avatar
Michael Hanus committed
290
INFO  Installing executable 'curry-check into '/home/joe/.cpm/bin'
Michael Hanus's avatar
Michael Hanus committed
291
292
\end{lstlisting}
%
Michael Hanus's avatar
Michael Hanus committed
293
Now, the tool \code{curry-check} is ready to use
Michael Hanus's avatar
Michael Hanus committed
294
295
296
297
298
if \code{\$HOME/.cpm/bin} is in your path
(see Section~\ref{sec:config} for details about changing the location
of this default path).


Michael Hanus's avatar
Michael Hanus committed
299
300
\subsection{Installing Applications of Packages}
\label{sec:installapp}
Michael Hanus's avatar
Michael Hanus committed
301
302

Some packages do not contain only useful libraries
Michael Hanus's avatar
Michael Hanus committed
303
304
but also application programs or tools.
In order to install the executables of such applications without
Michael Hanus's avatar
Michael Hanus committed
305
explicitly checking out the package in some local directory,
Michael Hanus's avatar
Michael Hanus committed
306
307
one can use the command
\begin{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
308
cypm install <package>
Michael Hanus's avatar
Michael Hanus committed
309
310
\end{lstlisting}
This command checks out the package in some internal directory
Michael Hanus's avatar
Michael Hanus committed
311
(default: \code{\$HOME/.cpm/app_packages}, see
Michael Hanus's avatar
Michael Hanus committed
312
Section~\ref{sec:config})
Michael Hanus's avatar
Michael Hanus committed
313
and installs the binary of the application provided by the package
Michael Hanus's avatar
Michael Hanus committed
314
315
316
317
318
319
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}
Michael Hanus's avatar
Michael Hanus committed
320
> cypm install spicey
Michael Hanus's avatar
Michael Hanus committed
321
322
323
324
325
326
327
328
329
330
331
$\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).


Michael Hanus's avatar
Michael Hanus committed
332
\subsection{Executing the Curry System in a Package}
Michael Hanus's avatar
Michael Hanus committed
333

Michael Hanus's avatar
Michael Hanus committed
334
335
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
Michael Hanus's avatar
Michael Hanus committed
336
modules provided. You can use the command \ccode{cypm curry} to start the
Michael Hanus's avatar
Michael Hanus committed
337
Curry system (which is either the compiler used to install CPM
Michael Hanus's avatar
Michael Hanus committed
338
or specified with the configuration option \code{CURRY_BIN},
Michael Hanus's avatar
Michael Hanus committed
339
see Section~\ref{sec:config}).
Michael Hanus's avatar
Michael Hanus committed
340
Any parameters given to \ccode{cypm curry} will be passed along verbatim to
Michael Hanus's avatar
Michael Hanus committed
341
342
343
the Curry system.
For example, the following will start the Curry system,
print the result of evaluating the expression \code{39+3}
Michael Hanus's avatar
Michael Hanus committed
344
345
346
and then quit.

\begin{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
347
> cypm curry :eval "39+3" :quit
Michael Hanus's avatar
Michael Hanus committed
348
349
\end{lstlisting}
%
Michael Hanus's avatar
Michael Hanus committed
350
351
To execute other Curry commands, such as \ccode{curry check},
with the package's dependencies available,
Michael Hanus's avatar
Michael Hanus committed
352
you can use the \ccode{cypm exec} command.
Michael Hanus's avatar
Michael Hanus committed
353
354
355
This command will set the \code{CURRYPATH} environment variable
and then execute the command given after \ccode{exec}.

Michael Hanus's avatar
Michael Hanus committed
356

Michael Hanus's avatar
Michael Hanus committed
357
358
\subsection{Using Packages Outside a Package}
\label{sec:meta-package}
Michael Hanus's avatar
Michael Hanus committed
359
360

In principle, packages can be used only inside another package
Michael Hanus's avatar
Michael Hanus committed
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
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}).
Michael Hanus's avatar
Michael Hanus committed
379
380
381
382
383

For instance, to use the libraries of the JSON package
in your application, one can use the following commands:
%
\begin{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
384
> cypm add -d json  # add 'json' dependency to meta-package
Michael Hanus's avatar
Michael Hanus committed
385
386
> cypm install      # download and install all dependencies
> cypm curry        # start Curry system with JSON libraries in load path
Michael Hanus's avatar
Michael Hanus committed
387
388
389
390
391
392
...
Prelude> :load JSON.Data
JSON.Data>
\end{lstlisting}
%

Michael Hanus's avatar
Michael Hanus committed
393
394
395
396
397
398
399
400
401
402
403
404
405
\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 
Michael Hanus's avatar
Michael Hanus committed
406
package. The \code{cypm link} command allows you to replace a dependency with
Michael Hanus's avatar
Michael Hanus committed
407
408
your own local copy.

Michael Hanus's avatar
Michael Hanus committed
409
\code{cypm link} takes a directory containing a copy of one of the current 
Michael Hanus's avatar
Michael Hanus committed
410
411
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
Michael Hanus's avatar
Michael Hanus committed
412
413
\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 
Michael Hanus's avatar
Michael Hanus committed
414
from the current package, your local copy is used instead of the one from the
Michael Hanus's avatar
Michael Hanus committed
415
global package cache. To remove any links, use \code{cypm upgrade} without any
Michael Hanus's avatar
Michael Hanus committed
416
417
418
419
arguments, which will clear the local package cache. See 
Section~\ref{sec:internals} for more information on the global and local package
caches.

Michael Hanus's avatar
Michael Hanus committed
420
421
422
\clearpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Michael Hanus's avatar
Michael Hanus committed
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
\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} 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
Michael Hanus's avatar
Michael Hanus committed
468
\code{cypm install} command). For example, if you are developing version $1.3.0$
Michael Hanus's avatar
Michael Hanus committed
469
470
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 
Michael Hanus's avatar
Michael Hanus committed
471
\code{cypm diff 1.2.6} command while in the directory of version $1.3.0$. 
Michael Hanus's avatar
Michael Hanus committed
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539

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. It will also generate a CurryCheck program that will 
compare the behavior of all exported functions in all exported modules whose
types have not changed and execute that program. 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 -#}| or \verb|{-# 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 -#}| 
so that CPM will not generate tests for them.


Michael Hanus's avatar
Michael Hanus committed
540
541
542
543
544
545
\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
Michael Hanus's avatar
Michael Hanus committed
546
\ccode{cypm add} command:
Michael Hanus's avatar
Michael Hanus committed
547
548
%
\begin{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
549
> cypm add --package mypackage
Michael Hanus's avatar
Michael Hanus committed
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
\end{lstlisting}
%
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.


Michael Hanus's avatar
Michael Hanus committed
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
\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 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} 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}
%
Michael Hanus's avatar
Michael Hanus committed
600
601
602
603
604
605
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
Michael Hanus's avatar
Michael Hanus committed
606
version is released.
Michael Hanus's avatar
Michael Hanus committed
607
608
609
610
611
612
613
614
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} 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
Michael Hanus's avatar
Michael Hanus committed
615
package index. This can be done with the \ccode{cypm add} command
Michael Hanus's avatar
Michael Hanus committed
616
617
618
619
620
(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
Michael Hanus's avatar
Michael Hanus committed
621
622
specification file to \url{packages@curry-language.org} in order to
publish it.
Michael Hanus's avatar
Michael Hanus committed
623
624


Michael Hanus's avatar
Michael Hanus committed
625
626
\clearpage

Michael Hanus's avatar
Michael Hanus committed
627
628
629
630
631
632
633
\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}
Michael Hanus's avatar
Michael Hanus committed
634
\item[\fbox{\code{REPOSITORY_PATH}}] The path to the index repository.
Michael Hanus's avatar
Michael Hanus committed
635
636
Default value: \code{\$HOME/.cpm/index}.

Michael Hanus's avatar
Michael Hanus committed
637
\item[\fbox{\code{PACKAGE_INSTALL_PATH}}] The path to the global package cache.
Michael Hanus's avatar
Michael Hanus committed
638
639
640
This is where all downloaded packages are stored.
Default value: \code{\$HOME/.cpm/packages}

Michael Hanus's avatar
Michael Hanus committed
641
\item[\fbox{\code{BIN_INSTALL_PATH}}] The path to the executables
Michael Hanus's avatar
Michael Hanus committed
642
643
644
645
646
647
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}

Michael Hanus's avatar
Michael Hanus committed
648
\item[\fbox{\code{APP_PACKAGE_PATH}}]
Michael Hanus's avatar
Michael Hanus committed
649
The path to the package cache where packages are checked out if only
Michael Hanus's avatar
Michael Hanus committed
650
651
their binaries are installed (see Section~\ref{sec:installapp}).
Default value: \code{\$HOME/.cpm/app_packages}.
Michael Hanus's avatar
Michael Hanus committed
652

Michael Hanus's avatar
Michael Hanus committed
653
654
655
656
657
\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}.

Michael Hanus's avatar
Michael Hanus committed
658
\item[\fbox{\code{CURRY_BIN}}]
Michael Hanus's avatar
Michael Hanus committed
659
660
661
662
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.
Michael Hanus's avatar
Michael Hanus committed
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680

\item[\fbox{\code{BASE_VERSION}}]
The version of the base libraries which is used for package installations.
In the default case, the base version is the version of the system libraries
used by the Curry compiler. These system libraries are also available
as package \ccode{base} so that they can listed as a dependency
in the package specification.
If the base version of the package is identical to the base version
of the Curry compiler used by CPM, the installed copy
of the base libraries is ignored.\footnote{Since the system libraries
of a Curry compiler are usually pre-compiled, the usage of the
system libraries instead of the \code{base} package might result
in faster compilation times.}
If one uses a different base version, e.g., enforced by a package
dependency or by setting this configuration variable,
then this version of the base package is used.
Thus, one can use a package even if the current compiler
has a different version of the base libraries.
Michael Hanus's avatar
Michael Hanus committed
681
682
\end{description}
%
Michael Hanus's avatar
Michael Hanus committed
683
684
685
686
Note that one write the option names also in lowercase or omit
the underscores. For instance, one can also write \code{currybin}
instead of \code{CURRY_BIN}.
Moreover, one can override the values of these configuration options
Michael Hanus's avatar
Michael Hanus committed
687
688
689
690
691
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}
Michael Hanus's avatar
Michael Hanus committed
692
> cypm --define bin_install_path=$\$$HOME/bin install spicey
Michael Hanus's avatar
Michael Hanus committed
693
694
695
\end{lstlisting}


Michael Hanus's avatar
Michael Hanus committed
696
697
\clearpage

Michael Hanus's avatar
Michael Hanus committed
698
699
700
\section{Some CPM Internals}
\label{sec:internals}

Michael Hanus's avatar
Michael Hanus committed
701
702
703
704
705
706
707
708
709
710
711
CPM's central package index is a Git repository containing package
specification files. A copy of this Git repository is stored on your
local system in the \code{\$HOME/.cpm/index} directory, 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}.  
Michael Hanus's avatar
Michael Hanus committed
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730

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.

Michael Hanus's avatar
Michael Hanus committed
731
732
733

\clearpage

Michael Hanus's avatar
Michael Hanus committed
734
735
736
\section{Command Reference}
\label{sec:cmd-reference}

Michael Hanus's avatar
Michael Hanus committed
737
738
739
740
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}
Michael Hanus's avatar
Michael Hanus committed
741
742
743
\item[\code{-d$\,|\,$--define $option$=$value$}:]
This option overrides the configuration options of CPM,
 see Section~\ref{sec:config}.
Michael Hanus's avatar
Michael Hanus committed
744
745
746
747
748
749
750
751
752
\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:
Michael Hanus's avatar
Michael Hanus committed
753
754

\begin{description}
Michael Hanus's avatar
Michael Hanus committed
755
756
757
758
759
760
\item[\fbox{\code{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.

Michael Hanus's avatar
Michael Hanus committed
761
762
763
764
\item[\fbox{\code{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]}}]
765
766
Prints information on the newest known version (compatible to the
current compiler) of the given package.
Michael Hanus's avatar
Michael Hanus committed
767
768
769
770
771
772
The option \code{--all} shows more information.

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

Michael Hanus's avatar
Michael Hanus committed
773
774
775
776
777
778
\item[\fbox{\code{list [--versions] [--csv]}}]
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 (compatible to the current compiler) is shown.
The option \code{--versions} shows all versions of the packages.
If a package is not compatible to the current compiler, then
Michael Hanus's avatar
Michael Hanus committed
779
the package version is shown in brackets (e.g., \ccode{(1.5.4)}).
Michael Hanus's avatar
Michael Hanus committed
780
781
The option \code{--csv} shows the information in CSV format.

782
783
784
785
786
787
\item[\fbox{\code{list --category [--csv]}}]
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.

Michael Hanus's avatar
Michael Hanus committed
788
\item[\fbox{\code{search [--module|--exec] $query$}}]
Michael Hanus's avatar
Michael Hanus committed
789
790
791
Searches the names, synopses, and exported module names of all 
packages of the central package index for occurrences of the given
search term.
Michael Hanus's avatar
Michael Hanus committed
792
793
794
If the option \code{--module} is set, then the given name
is searched in the list of exported modules.
Thus, the package
Michael Hanus's avatar
Michael Hanus committed
795
796
797
exporting the module \code{JSON.Data} can be found by the command
%
\begin{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
798
> cypm search --module JSON.Data
Michael Hanus's avatar
Michael Hanus committed
799
\end{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
800
801
802
803
804
805
%
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}
Michael Hanus's avatar
Michael Hanus committed
806
> cypm search --exec show
Michael Hanus's avatar
Michael Hanus committed
807
808
809
810
\end{lstlisting}
%
lists all packages where the name of the executable contains the
string \ccode{show}.
Michael Hanus's avatar
Michael Hanus committed
811

Michael Hanus's avatar
Michael Hanus committed
812
813
\item[\fbox{\code{update}}]
Updates the local copy of the central package index
Michael Hanus's avatar
Michael Hanus committed
814
to the newest available version.
Michael Hanus's avatar
Michael Hanus committed
815
816
817
818
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}.
Michael Hanus's avatar
Michael Hanus committed
819

Michael Hanus's avatar
Michael Hanus committed
820
821
\item[\fbox{\code{install}}]
Installs all dependencies of the current package.
Michael Hanus's avatar
Michael Hanus committed
822
Furthermore, if the current package contains an executable application,
Michael Hanus's avatar
Michael Hanus committed
823
824
the application is compiled and the executable is installed
(unless the option \code{-n} or \code{--noexec} is set).
Michael Hanus's avatar
Michael Hanus committed
825
826
827
828
With the option \code{-x} or \code{--exec}, the executable
is installed without installing all dependencies again.
This is useful to speed up the re-installation of a previously
installed application.
Michael Hanus's avatar
Michael Hanus committed
829

Michael Hanus's avatar
Michael Hanus committed
830
831
832
833
834
835
836
837
\item[\fbox{\code{install $package$ [--$pre$]}}]
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.
Michael Hanus's avatar
Michael Hanus committed
838

Michael Hanus's avatar
Michael Hanus committed
839
\item[\fbox{\code{install $package$ $version$}}]
Michael Hanus's avatar
Michael Hanus committed
840
Installs the application provided by a specific version of a package.
Michael Hanus's avatar
Michael Hanus committed
841
842
843
844
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}).
Michael Hanus's avatar
Michael Hanus committed
845
846
847
848
849
850

\item[\fbox{\code{install $package$.zip}}] 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.

Michael Hanus's avatar
Michael Hanus committed
851
852
853
854
855
856
857
858
859
860
\item[\fbox{\code{uninstall}}]
Uninstalls the executable installed for the current package.

\item[\fbox{\code{uninstall $package$}}]
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$}}]
Uninstalls a specific version
of a package from the global package cache.
Michael Hanus's avatar
Michael Hanus committed
861

Michael Hanus's avatar
Michael Hanus committed
862
863
\item[\fbox{\code{uninstall $package$ $version$}}]
Uninstalls a specific version
Michael Hanus's avatar
Michael Hanus committed
864
865
866
of a package from the global package cache.

\item[\fbox{\code{checkout $package$ [--$pre$]}}]
867
868
Checks out the newest version (compatible to the current compiler)
of a package into the local directory \code{$package$}
Michael Hanus's avatar
Michael Hanus committed
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
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$}}]
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}}]
Upgrades all dependencies of the current package to
the newest compatible version.

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

\item[\fbox{\code{deps}}] Does a dependency resolution run for the current 
package and prints out the results. The result is either a list of all package
versions chosen or a description of the conflict encountered during dependency
resolution.
Michael Hanus's avatar
Michael Hanus committed
889
890
Using the option \code{--path]}, only the value of \code{CURRYPATH} required
to load modules of this package is shown.
Michael Hanus's avatar
Michael Hanus committed
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905

\item[\fbox{\code{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.

906
\item[\fbox{\code{doc}}]
Michael Hanus's avatar
Michael Hanus committed
907
908
909
910
911
912
913
914
915
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.
Michael Hanus's avatar
Michael Hanus committed
916
917
The actual documentation will be stored in the subdirectory
\code{$name$-$version$} of the documentation directory.
Michael Hanus's avatar
Michael Hanus committed
918
919

The API documentation in HTML format is generated with CurryDoc.
920
921
922
923
924
925
926
927
928
929
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.
Michael Hanus's avatar
Michael Hanus committed
930

Michael Hanus's avatar
Michael Hanus committed
931
In the default case, modules contained in packages used by the current package
Michael Hanus's avatar
Michael Hanus committed
932
933
are not documented. Instead, it is assumed that these packages are
already documented\footnote{See
Michael Hanus's avatar
Michael Hanus committed
934
935
936
\url{http://www.informatik.uni-kiel.de/~curry/cpm/}
for the documentation of all packages. This default location
can be changed with the option \code{--url}.}
Michael Hanus's avatar
Michael Hanus committed
937
938
939
940
941
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.

Michael Hanus's avatar
Michael Hanus committed
942
943
944
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).
945

Michael Hanus's avatar
Michael Hanus committed
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
\item[\fbox{\code{diff [$version$]}}]
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.
Using the option \code{--modules}, one can also specify a comma-separated
list of module names to be compared. Without this option,
all exported modules are compared.

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}).

\item[\fbox{\code{exec $command$}}] 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$}}] Executes the Curry compiler with the 
Michael Hanus's avatar
Michael Hanus committed
974
975
dependencies of the current package available.
Any arguments are passed verbatim to the compiler.
Michael Hanus's avatar
Michael Hanus committed
976
977
978
979

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

Michael Hanus's avatar
Michael Hanus committed
980
981
\item[\fbox{\code{add --package $dir$ [--force]}}]
Copies the package contained in directory $dir$ into the local copy
Michael Hanus's avatar
Michael Hanus committed
982
983
984
985
986
987
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.

Michael Hanus's avatar
Michael Hanus committed
988
\item[\fbox{\code{add --dependency $package$ [--force]}}]
Michael Hanus's avatar
Michael Hanus committed
989
990
991
992
993
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}).
Michael Hanus's avatar
Michael Hanus committed
994
995
996
The option \ccode{--force} allows to overwrite existing dependencies
in the package description file.

Michael Hanus's avatar
Michael Hanus committed
997
\item[\fbox{\code{clean}}] Cleans the current package from the
Michael Hanus's avatar
Michael Hanus committed
998
generated auxiliary files, e.g., intermediate Curry files,
Michael Hanus's avatar
Michael Hanus committed
999
1000
1001
1002
1003
1004
installed dependent packages, etc.
Note that a binary installed in the CPM \code{bin} directory
(by the \code{install} command) will not be removed.
Hence, this command can be used to clean an application package
after installing the application.

Michael Hanus's avatar
Michael Hanus committed
1005
1006
\item[\fbox{\code{new $project$}}]
Creates a new project package with the given name and some template files.
Michael Hanus's avatar
Michael Hanus committed
1007
1008
\end{description}

Michael Hanus's avatar
Michael Hanus committed
1009

Michael Hanus's avatar
Michael Hanus committed
1010
1011
\clearpage

Michael Hanus's avatar
Michael Hanus committed
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
\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*}}] The name of the package. Must only contain ASCII 
letters, digits, hyphens and underscores. Must start with a letter.

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

\item[\fbox{\code{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
Michael Hanus's avatar
Michael Hanus committed
1027
1028
1029
1030
1031
angle brackets, e.g.,
\begin{lstlisting}
John Doe <john@doe.com>
\end{lstlisting}
Multiple authors should be separated by commas.
Michael Hanus's avatar
Michael Hanus committed
1032
1033
1034
1035
1036
1037

\item[\fbox{\code{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.

Michael Hanus's avatar
Michael Hanus committed
1038
The suggested format is a name followed by an email address in
Michael Hanus's avatar
Michael Hanus committed
1039
1040
1041
1042
angle brackets, e.g.,
\begin{lstlisting}
John Doe <john@doe.com>
\end{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
1043
1044
Multiple maintainers should be separated by commas.

Michael Hanus's avatar
Michael Hanus committed
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
\item[\fbox{\code{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}}] A longer form description of what the package 
does.

\item[\fbox{\code{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}}] 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}}] 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}}] Copyright information regarding the package.

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

Michael Hanus's avatar
Michael Hanus committed
1072
1073
1074
\item[\fbox{\code{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.
Michael Hanus's avatar
Michael Hanus committed
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090

\item[\fbox{\code{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*}}] 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}.

\item[\fbox{\code{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.

1091
1092
The compiler compatibility of a package is also relevant when
some version of a package should be examined or installed
Michael Hanus's avatar
Michael Hanus committed
1093
(with CPM commands \code{info}, \code{checkout}, \code{install}).
1094
1095
1096
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
Michael Hanus's avatar
Michael Hanus committed
1097
(see also Section~\ref{sec:config} for configuration option \code{CURRY_BIN})
1098
1099
1100
1101
1102
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.

Michael Hanus's avatar
Michael Hanus committed
1103
1104
1105
1106
\item[\fbox{\code{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.

Michael Hanus's avatar
Michael Hanus committed
1107
1108
1109
1110
1111
1112
1113
\item[\fbox{\code{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.

Michael Hanus's avatar
Michael Hanus committed
1114
1115
\item[\fbox{\code{exportedModules}}] A list of modules intended for use by 
consumers of the package.
Michael Hanus's avatar
Michael Hanus committed
1116
1117
These are the modules compared by the \code{cypm diff}
command (and tested by the \code{cypm test} command if a list of
Michael Hanus's avatar
Michael Hanus committed
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
test modules is not provided).
Note that modules not in this list are still accessible to consumers
of the package.

\item[\fbox{\code{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}}]
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}.
Michael Hanus's avatar
Michael Hanus committed
1147
1148
1149
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.
Michael Hanus's avatar
Michael Hanus committed
1150
1151
1152
1153
1154
1155
For instance, a possible specification could be as follows:
%
\begin{lstlisting}
{
  ...,
  "executable": {
Michael Hanus's avatar
Michael Hanus committed
1156
    "name": "cypm",
Michael Hanus's avatar
Michael Hanus committed
1157
1158
1159
    "main": "CPM.Main",
    "options": { "kics2" : ":set rts -T" }
   }
Michael Hanus's avatar
Michael Hanus committed
1160
1161
1162
1163
}
\end{lstlisting}
%
If a package contains an \code{executable} specification,
Michael Hanus's avatar
Michael Hanus committed
1164
the command \code{cypm install} also compiles the main module
Michael Hanus's avatar
Michael Hanus committed
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
and installs the executable in the \code{bin} install directory of CPM
(see Section~\ref{sec:config} for details).

\item[\fbox{\code{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
Michael Hanus's avatar
Michael Hanus committed
1187
by the command \code{cypm test}.
Michael Hanus's avatar
Michael Hanus committed
1188
1189
If no test suite is defined, all (exported) modules are tested
in the directory \code{src}.
Michael Hanus's avatar
Michael Hanus committed
1190
1191
A test suite can also contain a field \code{options}
which defines a string of options passed to the call to CurryCheck.
Michael Hanus's avatar
Michael Hanus committed
1192

Michael Hanus's avatar
Michael Hanus committed
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
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.
Michael Hanus's avatar
Michael Hanus committed
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
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",
Michael Hanus's avatar
Michael Hanus committed
1214
       "options": "-v",
Michael Hanus's avatar
Michael Hanus committed
1215
       "script": "test.sh"
Michael Hanus's avatar
Michael Hanus committed
1216
1217
     },
     { "src-dir": "examples",
Michael Hanus's avatar
Michael Hanus committed
1218
       "options": "-m80",
Michael Hanus's avatar
Michael Hanus committed
1219
1220
1221
1222
1223
1224
       "modules": [ "Nats", "Ints" ]
     }
  ]
}
\end{lstlisting}

Michael Hanus's avatar
Michael Hanus committed
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
\item[\fbox{\code{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": "pfdlatex -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
Michael Hanus's avatar
Michael Hanus committed
1249
(see description of the command \code{cypm doc}).
Michael Hanus's avatar
Michael Hanus committed
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
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}

Michael Hanus's avatar
Michael Hanus committed
1268
\end{description}
Michael Hanus's avatar
Michael Hanus committed
1269
%
Michael Hanus's avatar
Michael Hanus committed
1270
1271
In order to get a compact overview over all metadata fields,
we show an example of a package specification where all fields
Michael Hanus's avatar
Michael Hanus committed
1272
1273
1274
1275
1276
1277
1278
1279
1280
are used:
%
\begin{lstlisting}
{
    "name": "PACKAGE_NAME",
    "version": "0.0.1",
    "author": "YOUR NAME <YOUR EMAIL ADDRESS>",
    "maintainer": "ANOTHER NAME <ANOTHER EMAIL ADDRESS>",
    "synopsis": "A ONE-LINE SUMMARY ABOUT THE PACKAGE",
Michael Hanus's avatar
Michael Hanus committed
1281
    "description": "A MORE DETAILED SUMMARY ABOUT THE PACKAGE",
Michael Hanus's avatar
Michael Hanus committed
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
    "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"
    },
    "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"
       }
    ],
Michael Hanus's avatar
Michael Hanus committed
1319
1320
1321
1322
1323
    "documentation": {
        "src-dir": "docs",
        "main"   : "manual.tex",
        "command": "pfdlatex -output-directory=OUTDIR manual.tex"
    },
Michael Hanus's avatar
Michael Hanus committed
1324
1325
1326
1327
1328
1329
1330
    "source": {
        "git": "URL OF THE GIT REPOSITORY",
        "tag": "$\$$version"
    }
}
\end{lstlisting}

Michael Hanus's avatar
Michael Hanus committed
1331

Michael Hanus's avatar
Michael Hanus committed
1332
1333
\clearpage

1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
\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}
Michael Hanus's avatar
Michael Hanus committed
1346
\item[\code{cypm clean}]~\\
1347
This command cleans the current package from
Michael Hanus's avatar
Michael Hanus committed
1348
generated auxiliary files (see Section~\ref{sec:cmd-reference}).
1349
Then you can re-install the package and packages on which it depends
Michael Hanus's avatar
Michael Hanus committed
1350
by the command \code{cypm install}.
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
\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
Michael Hanus's avatar
Michael Hanus committed
1361
by the command \code{cypm update}.
1362
1363
1364
\end{description}


Michael Hanus's avatar
Michael Hanus committed
1365
\end{document}
Michael Hanus's avatar
Michael Hanus committed
1366
1367

%  LocalWords:  CPM versioning