manual.tex 56.8 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
\emph{Git}\footnote{\url{http://www.git-scm.com}},
Michael Hanus's avatar
Michael Hanus committed
90
91
\emph{curl}\footnote{\url{https://curl.haxx.se}},
\emph{tar},
Michael Hanus's avatar
Michael Hanus committed
92
93
94
95
96
97
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
98
99
100
101
102
103
104
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
105
106
107
108
109
110
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
111
a binary called \code{cypm} in the \code{bin} subdirectory. Put
Michael Hanus's avatar
Michael Hanus committed
112
113
this binary somewhere on your path.

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

\clearpage

\section{Starting the Curry Package Manager}

Michael Hanus's avatar
Michael Hanus committed
119
If the binary \code{cypm} is on your path, execute the command
Michael Hanus's avatar
Michael Hanus committed
120
121
%
\begin{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
122
> cypm update
Michael Hanus's avatar
Michael Hanus committed
123
124
125
126
127
128
\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.

Michael Hanus's avatar
Michael Hanus committed
129
Afterwards, you can show a list of all packages in this index by
Michael Hanus's avatar
Michael Hanus committed
130
131
%
\begin{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
132
> cypm list
Michael Hanus's avatar
Michael Hanus committed
133
134
135
136
137
\end{lstlisting}
%
The command
%
\begin{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
138
> cypm info PACKAGE
Michael Hanus's avatar
Michael Hanus committed
139
140
141
142
143
144
\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
145
> cypm search QUERY
Michael Hanus's avatar
Michael Hanus committed
146
147
148
149
150
151
152
153
\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
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
208

\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
209
210
\clearpage

Michael Hanus's avatar
Michael Hanus committed
211
212
213
214
215
216
217
218
219
220
221
222
223
224
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\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
225
starting a new project, use the \code{cypm new <project-name>} command, which 
Michael Hanus's avatar
Michael Hanus committed
226
227
228
229
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
230
Then declare the dependencies inside the new \code{package.json} file, e.g.:
Michael Hanus's avatar
Michael Hanus committed
231
232
233
234
235

\begin{lstlisting}
{
  ...,
  "dependencies": {
Michael Hanus's avatar
Michael Hanus committed
236
    "base": ">= 1.0.0, < 2.0.0",
Michael Hanus's avatar
Michael Hanus committed
237
238
239
240
241
    "json": "~> 1.1.0"
  }
}
\end{lstlisting}
%
Michael Hanus's avatar
Michael Hanus committed
242
243
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
244
245
246
247
248
able to load the JSON package's modules in your Curry session.


\subsection{Installing and Updating Dependencies}

Michael Hanus's avatar
Michael Hanus committed
249
To install the current package's dependencies, run \code{cypm install}. This will
Michael Hanus's avatar
Michael Hanus committed
250
251
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
252
\code{cypm install} will always prefer the versions it installed on a previous
Michael Hanus's avatar
Michael Hanus committed
253
254
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
255
256
257
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
258
259
260
261
262
263
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
264
then the command \code{cypm install} also compiles the application
Michael Hanus's avatar
Michael Hanus committed
265
266
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
267
The installation of executables can be suppressed by the
Michael Hanus's avatar
Michael Hanus committed
268
\code{cypm install} option \code{-n} or \code{--noexec}.
Michael Hanus's avatar
Michael Hanus committed
269
270
271
272
273
274
275
276


\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
277
cypm checkout <package>
Michael Hanus's avatar
Michael Hanus committed
278
279
280
\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
281
282
For instance, to install \code{curry-check},
a property-testing tool for Curry,
Michael Hanus's avatar
Michael Hanus committed
283
284
285
one can check out the most recent version and install the tool:
%
\begin{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
286
> cypm checkout currycheck
Michael Hanus's avatar
Michael Hanus committed
287
288
$\ldots$ Package 'currycheck-1.0.1' checked out into directory 'currycheck'.
> cd currycheck
Michael Hanus's avatar
Michael Hanus committed
289
> cypm install
Michael Hanus's avatar
Michael Hanus committed
290
$\ldots$
Michael Hanus's avatar
Michael Hanus committed
291
INFO  Installing executable 'curry-check into '/home/joe/.cpm/bin'
Michael Hanus's avatar
Michael Hanus committed
292
293
\end{lstlisting}
%
Michael Hanus's avatar
Michael Hanus committed
294
Now, the tool \code{curry-check} is ready to use
Michael Hanus's avatar
Michael Hanus committed
295
296
297
298
299
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
300
301
\subsection{Installing Applications of Packages}
\label{sec:installapp}
Michael Hanus's avatar
Michael Hanus committed
302
303

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

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

\begin{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
348
> cypm curry :eval "39+3" :quit
Michael Hanus's avatar
Michael Hanus committed
349
350
\end{lstlisting}
%
Michael Hanus's avatar
Michael Hanus committed
351
352
To execute other Curry commands, such as \ccode{curry check},
with the package's dependencies available,
Michael Hanus's avatar
Michael Hanus committed
353
you can use the \ccode{cypm exec} command.
Michael Hanus's avatar
Michael Hanus committed
354
355
356
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
357

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

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

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
385
> cypm add -d json  # add 'json' dependency to meta-package
Michael Hanus's avatar
Michael Hanus committed
386
387
> 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
388
389
390
391
392
393
...
Prelude> :load JSON.Data
JSON.Data>
\end{lstlisting}
%

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

Michael Hanus's avatar
Michael Hanus committed
410
\code{cypm link} takes a directory containing a copy of one of the current 
Michael Hanus's avatar
Michael Hanus committed
411
412
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
413
414
\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
415
from the current package, your local copy is used instead of the one from the
Michael Hanus's avatar
Michael Hanus committed
416
global package cache. To remove any links, use \code{cypm upgrade} without any
Michael Hanus's avatar
Michael Hanus committed
417
418
419
420
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
421
422
423
\clearpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Michael Hanus's avatar
Michael Hanus committed
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
468
\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
469
\code{cypm install} command). For example, if you are developing version $1.3.0$
Michael Hanus's avatar
Michael Hanus committed
470
471
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
472
\code{cypm diff 1.2.6} command while in the directory of version $1.3.0$. 
Michael Hanus's avatar
Michael Hanus committed
473
474
475
476

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 
Michael Hanus's avatar
Michael Hanus committed
477
478
479
480
481
482
483
484
485
486
487
488
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.
Michael Hanus's avatar
Michael Hanus committed
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
540
541
542
543
544
545
546
547
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
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
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:
\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}.

Michael Hanus's avatar
Michael Hanus committed
569

Michael Hanus's avatar
Michael Hanus committed
570
571
572
573
574
575
\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
576
\ccode{cypm add} command:
Michael Hanus's avatar
Michael Hanus committed
577
578
%
\begin{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
579
> cypm add --package mypackage
Michael Hanus's avatar
Michael Hanus committed
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
\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
596
597
598
599
600
601
602
\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.

Michael Hanus's avatar
Michael Hanus committed
603
604
605
CPM supports ZIP (suffix \ccode{.zip}) or
compressed TAR (suffix \ccode{.tar.gz}) files
accessible over HTTP as well as Git repositories as 
Michael Hanus's avatar
Michael Hanus committed
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
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
632
633
634
635
636
637
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
638
version is released.
Michael Hanus's avatar
Michael Hanus committed
639
640
641
642
643
644
645
646
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
647
package index. This can be done with the \ccode{cypm add} command
Michael Hanus's avatar
Michael Hanus committed
648
649
650
651
652
(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
653
654
specification file to \url{packages@curry-language.org} in order to
publish it.
Michael Hanus's avatar
Michael Hanus committed
655
656


Michael Hanus's avatar
Michael Hanus committed
657
658
\clearpage

Michael Hanus's avatar
Michael Hanus committed
659
660
661
662
663
664
665
\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
666
667
668
669
670
671
\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.

\item[\fbox{\code{REPOSITORY_PATH}}] The path to the index of all packages.
Michael Hanus's avatar
Michael Hanus committed
672
673
Default value: \code{\$HOME/.cpm/index}.

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

Michael Hanus's avatar
Michael Hanus committed
678
\item[\fbox{\code{BIN_INSTALL_PATH}}] The path to the executables
Michael Hanus's avatar
Michael Hanus committed
679
680
681
682
683
684
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
685
\item[\fbox{\code{APP_PACKAGE_PATH}}]
Michael Hanus's avatar
Michael Hanus committed
686
The path to the package cache where packages are checked out if only
Michael Hanus's avatar
Michael Hanus committed
687
688
their binaries are installed (see Section~\ref{sec:installapp}).
Default value: \code{\$HOME/.cpm/app_packages}.
Michael Hanus's avatar
Michael Hanus committed
689

Michael Hanus's avatar
Michael Hanus committed
690
691
692
693
694
\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
695
\item[\fbox{\code{CURRY_BIN}}]
Michael Hanus's avatar
Michael Hanus committed
696
697
698
699
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
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717

\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
718
719
\end{description}
%
Michael Hanus's avatar
Michael Hanus committed
720
721
722
723
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
724
725
726
727
728
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
729
> cypm --define bin_install_path=$\$$HOME/bin install spicey
Michael Hanus's avatar
Michael Hanus committed
730
731
732
\end{lstlisting}


Michael Hanus's avatar
Michael Hanus committed
733
734
\clearpage

Michael Hanus's avatar
Michael Hanus committed
735
736
737
\section{Some CPM Internals}
\label{sec:internals}

Michael Hanus's avatar
Michael Hanus committed
738
739
740
741
742
CPM's central package index is 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}.
A copy of this index is stored on your
Michael Hanus's avatar
Michael Hanus committed
743
744
745
746
747
748
749
750
751
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
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770

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
771
772
773

\clearpage

Michael Hanus's avatar
Michael Hanus committed
774
775
776
\section{Command Reference}
\label{sec:cmd-reference}

Michael Hanus's avatar
Michael Hanus committed
777
778
779
780
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
781
782
783
\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
784
785
786
787
788
789
790
791
792
\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
793
794

\begin{description}
Michael Hanus's avatar
Michael Hanus committed
795
796
797
798
799
800
\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
801
802
803
804
\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]}}]
805
806
Prints information on the newest known version (compatible to the
current compiler) of the given package.
Michael Hanus's avatar
Michael Hanus committed
807
808
809
810
811
812
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
813
814
815
816
817
818
\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
819
the package version is shown in brackets (e.g., \ccode{(1.5.4)}).
Michael Hanus's avatar
Michael Hanus committed
820
821
The option \code{--csv} shows the information in CSV format.

822
823
824
825
826
827
\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
828
\item[\fbox{\code{search [--module|--exec] $query$}}]
Michael Hanus's avatar
Michael Hanus committed
829
830
831
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
832
833
834
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
835
836
837
exporting the module \code{JSON.Data} can be found by the command
%
\begin{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
838
> cypm search --module JSON.Data
Michael Hanus's avatar
Michael Hanus committed
839
\end{lstlisting}
Michael Hanus's avatar
Michael Hanus committed
840
841
842
843
844
845
%
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
846
> cypm search --exec show
Michael Hanus's avatar
Michael Hanus committed
847
848
849
850
\end{lstlisting}
%
lists all packages where the name of the executable contains the
string \ccode{show}.
Michael Hanus's avatar
Michael Hanus committed
851

Michael Hanus's avatar
Michael Hanus committed
852
853
\item[\fbox{\code{update}}]
Updates the local copy of the central package index
Michael Hanus's avatar
Michael Hanus committed
854
to the newest available version.
Michael Hanus's avatar
Michael Hanus committed
855
856
857
858
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
859
860
The option \code{--url} allows to specify a different URL
for the central package index (might be useful for experimental purposes).
Michael Hanus's avatar
Michael Hanus committed
861

Michael Hanus's avatar
Michael Hanus committed
862
863
\item[\fbox{\code{install}}]
Installs all dependencies of the current package.
Michael Hanus's avatar
Michael Hanus committed
864
Furthermore, if the current package contains an executable application,
Michael Hanus's avatar
Michael Hanus committed
865
866
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
867
868
869
870
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
871

Michael Hanus's avatar
Michael Hanus committed
872
873
874
875
876
877
878
879
\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
880

Michael Hanus's avatar
Michael Hanus committed
881
\item[\fbox{\code{install $package$ $version$}}]
Michael Hanus's avatar
Michael Hanus committed
882
Installs the application provided by a specific version of a package.
Michael Hanus's avatar
Michael Hanus committed
883
884
885
886
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
887
888
889
890
891
892

\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
893
894
895
896
897
898
899
900
901
902
\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
903

Michael Hanus's avatar
Michael Hanus committed
904
905
\item[\fbox{\code{uninstall $package$ $version$}}]
Uninstalls a specific version
Michael Hanus's avatar
Michael Hanus committed
906
907
908
of a package from the global package cache.

\item[\fbox{\code{checkout $package$ [--$pre$]}}]
909
910
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
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
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
931
932
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
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947

\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.

948
\item[\fbox{\code{doc}}]
Michael Hanus's avatar
Michael Hanus committed
949
950
951
952
953
954
955
956
957
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
958
959
The actual documentation will be stored in the subdirectory
\code{$name$-$version$} of the documentation directory.
Michael Hanus's avatar
Michael Hanus committed
960
961

The API documentation in HTML format is generated with CurryDoc.
962
963
964
965
966
967
968
969
970
971
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
972

Michael Hanus's avatar
Michael Hanus committed
973
In the default case, modules contained in packages used by the current package
Michael Hanus's avatar
Michael Hanus committed
974
975
are not documented. Instead, it is assumed that these packages are
already documented\footnote{See
Michael Hanus's avatar
Michael Hanus committed
976
977
978
\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
979
980
981
982
983
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
984
985
986
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).
987

Michael Hanus's avatar
Michael Hanus committed
988
989
990
991
992
993
994
\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.
Michael Hanus's avatar
Michael Hanus committed
995
996
997
998
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.
Michael Hanus's avatar
Michael Hanus committed
999
1000

As described in Section~\ref{sec:semantic-versioning},
For faster browsing, not all history is shown. View entire blame