Revision 0.8.0
Copyright © 2002-2015 Mehdi Dogguy, Stephane Glondu, Sylvain Le Gall, Sven Luther, Samuel Mimram, Ralf Treinen, Stefano Zacchiroli
This manual is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
A copy of the GNU General Public License is available as /usr/share/common-licenses/GPL-3
on Debian GNU/Linux systems or on the World Wide Web at The GNU Public
Licence.
Table of Contents
List of Examples
Build checklist
Build without ocamlopt
Howto install using ocamlfind
dh-ocaml stuff: howto use, what he can guess
need to depend on -dev package outside ocaml package
Table of Contents
The availability of the native compiler can be tested in the
debian/rules
file by testing the
possibility of executing
/usr/bin/ocamlopt
, and build the bytecode
version or the native version of the program according to the
result of the test. This is a sample snippet of
debian/rules
doing so:
build-stamp: dh_testdir if [ -x /usr/bin/ocamlopt ]; then \ $(MAKE) opt; \ else \ $(MAKE) all; \ fi
The following is a snippet of a sample
debian/control
:
Package: spamoracle-byte Architecture: all Depends: ocaml-base-${F:OCamlABI} Provides: spamoracle Conflicts: spamoracle Replaces: spamoracle
The following its pairing debian/rules
snippet:
OCAMLABI := $(shell ocamlc -version) ... binary-indep: build install dh_gencontrol -i -- -VF:OCamlABI="$(OCAMLABI)"
In the case where there is only one package, which provides
either a native version where available or a bytecode version
otherwise, the dependency on
ocaml-base-[ocaml-version]
should be
added only when the package is built in native mode. For
example, the debian/control
of
approx
contains:
Package: approx Architecture: any Depends: ${shlibs:Depends}, ${F:OCamlRun}, adduser, bzip2, curl
and the corresponding debian/rules
contains:
OCAMLABI = $(shell ocamlc -version) BYTECODE = $(shell [ -x /usr/bin/ocamlopt ] || echo yes) OCAMLRUN = $(if $(BYTECODE),ocaml-base-$(OCAMLABI)) ... binary-arch: ... dh_gencontrol -- -VF:OCamlRun="$(OCAMLRUN)"
TODO: section should be simlified by using dh-ocaml
To help maintainers of OCaml-related packages in adhering to this policy, a
class for the CDBS
build system has been made available and is shipped as part of
the ocaml
package. Please consider using it in your
packages at it will both ease your work and permit to perform changes to a
wide range of packages acting on a single piece of software (the CDBS class
itself).
To use the class in your package it is enough to include the file
/usr/share/cdbs/1/rules/ocaml.mk
from your
debian/rules
. If you use debhelper (please do) you
should include the OCaml class after the debhelper on. A typical
debian/rules
heading for a package using plain Makefile
(i.e. no autotools) and dpatch is as follows:
#!/usr/bin/make -f include /usr/share/cdbs/1/rules/dpatch.mk include /usr/share/cdbs/1/rules/debhelper.mk include /usr/share/cdbs/1/class/makefile.mk include /usr/share/cdbs/1/rules/ocaml.mk
For an example of such a package see the pcre-ocaml
Debian source package.
A detailed description of how to use the OCaml CDBS class should be provided in this section, but at the time of writing is a future work :-). In the meantime if you know CDBS, the .mk files which compose the OCaml class are well commented and they should give you enough information to customize the build process of your package. The latest version of them is available in the repository of the The Debian OCaml Task Force and can be browsed on the web:
ocaml-vars.mk
contains (Makefile) convenience variables which can be used in
debian/rules
ocaml.mk
implements the class logic
Debhelper provides since version 7 the dh
tool which automatizes in simply and standard cases completely the
tasks to be done by debian/rules
, and which
provides for various means to adapt to complex or non-standard cases
(see dh(1)). The
dh-ocaml package provides since version
0.9.0 a ocaml addon to dh.
Example 2.1. A debian/rules
file using dh
#!/usr/bin/make -f %: dh $@ --with ocaml
This package must build-depend on dh-ocaml (>= 0.9.0)
.
Table of Contents
This section is still under construction!
(Hopefully) All OCaml-related Debian packages are maintained using centralized Git repositories. This practice reduce the efforts needed to contribute work inside The Debian OCaml Task Force and, in case of need, provides a place where to massively perform changes to all OCaml-related Debian packages.
In the past, we were using Subversion, but we are progressively migrating our packages to Git.
Debian users can benefit knowing we are using a Git repository (they can for instance subscribe to the RSS feed for changes or have a place where to look for finding patches corresponding to bugs tagged "pending" in the BTS).
For this reason it is recommended to add the
Vcs-Git
and Vcs-Browser
fields to the
debian/control
of packages maintained in
The Debian OCaml Task Force Git repository. Its name specifies that
we are using Git as our Version Control System
(VCS); their values are the URLs pointing to
the package's repository and to a browsable view of the same
directory. See the
Debian
Developer's Reference for more information about these
fields.
The general scheme for using the fields are thus:
Vcs-Git: git://git.debian.org/git/pkg-ocaml-maint/packages/PACKAGE_NAME.git Vcs-Browser: http://git.debian.org/?p=pkg-ocaml-maint/packages/PACKAGE_NAME.git
Example 3.1. Usage example of the Vcs-* fields, from the findlib package
Source: findlib Section: devel Priority: optional Maintainer: Debian OCaml Maintainers <debian-ocaml-maint@lists.debian.org> Uploaders: Stefano Zacchiroli <zack@debian.org> Build-Depends: debhelper (>> 5.0.0), ocaml (>= 3.11.0), camlp4 (>= 3.11.0), m4, gawk | awk, dpatch, cdbs, dh-ocaml Standards-Version: 3.8.0 Vcs-Git: git://git.debian.org/git/pkg-ocaml-maint/packages/findlib.git Vcs-Browser: http://git.debian.org/?p=pkg-ocaml-maint/packages/findlib.git Homepage: http://projects.camlcity.org/projects/findlib.html Package: ocaml-findlib Section: devel Architecture: any Depends: ocaml-${F:OCamlABI}, ${shlibs:Depends}, ${misc:Depends} Description: Management tool for OCaml programming language libraries ...
This document assumes that you have the following packages
installed: git-buildpackage
and pristine-tar
.
There is one Git repository per package. To get the list of packages managed with git, you can use the following command (your ssh must be configured properly):
ssh git.debian.org ls /git/pkg-ocaml-maint/packages
You can obtain a copy of the repository for a package with:
checkout-d-o-m-git-repo package
The checkout-d-o-m-git-repos script is available in the Subversion repository. You can get a copy with:
svn co svn://svn.debian.org/svn/pkg-ocaml-maint/trunk/projects/git-guide
You must be member of the Debian OCaml Task Force in order to have the right to push to the central repository.
We keep all upstream sources under Git control, in a branch called upstream. This branch usually consists of successive unpacked upstream tarballs. When importing a new upstream tarball, the following command should be used:
git-import-orig --pristine-tar [--no-dch] <name_version.orig.tar.gz>
The --pristine-tar
is mandatory to store
information for reconstructing the upstream tarball from the
repository. That information is not suited for human use and
is stored in the pristine-tar
branch. Optionally, --no-dch
can be given
to automatically update the Debian changelog (without
committing it).
The master branch contains upstream sources
along with the debian/
directory. git-import-orig
automatically
creates a (local) tag in the upstream branch, and
merges upstream
into master when importing a new
tarball. Changes related to Debian should be done in this
branch.
Let's take dose2 as an example. The following command (the new-d-o-m-git-repo is available at the same location of checkout-d-o-m-git-repo):
new-d-o-m-git-repo dose2 /some/where/dose2-1.2.tar.gz
will create the remote repository on Alioth, set up
notifications, and inject the given tarball in the repository
in the upstream branch
(using pristine-tar
). More
details there. You
can then check it out and start using it.
If the tarball name is missing, new-d-o-m-git-repo will check that the current directory is a git repository, and then push it to Alioth. This allows you to create the repository locally, work on it, and only push it when it is in good shape. It is recommended to check it out after, and use the checked out version, to make sure everything went well, and to have local branches tracking remote ones.
Put the following in debian/gbp.conf
:
# Configuration file for git-buildpackage and friends [DEFAULT] # the default branch for upstream sources: upstream-branch = upstream # the default branch for the debian patch: debian-branch = master # use pristine-tar: pristine-tar = True
The first two settings are not really useful since they are
the defaults, but it might be handy to have them around when
working with several
branches. The pristine-tar
is necessary
if tarballs are imported. Please see
the git-buildpackage documentation
for complete information.
If you tried git-buildpackage
before writing your debian/gbp.conf
,
remember to delete the .orig
tarball, and
rebuild after
writing debian/gbp.conf
. Alternatively,
you can invoke git-buildpackage
with the --git-pristine-tar
option.
Please refer to the git-builpackage documentation for more complete information. Here is just a quick guide.
All options, except those starting on --git
, are passed to
dpkg-buildpackage. Hence, basic
usage should be something like this (from the root of the
repository): git-buildpackage -rfakeroot -uc
-us. The package will be built in place, and the
result will be put in the parent directory.
git-buildpackage will complain when
your repository is not clean. You may use the
option --git-ignore-new
to override this
behaviour.
If your package is ready for upload you may use
the --git-tag
option for the final
build. This will create a tag in your local repository.
Provided you have commited all your changes to the Git
repository, this will after a successful build of the package
create a tag for the current version.
Tags created by git-import-orig and git-buildpackage are not automatically pushed, you have to push them explicitly with the following command: git push --tags. Be careful if you use local tags!
You can add the --dry-run option to git push to see what will be done.
To build with pbuilder (or cowbuilder), use the following:
git-buildpackage \ --git-builder="pdebuild --debbuildopts '-I.git -i\.git -uc -us'" \ --git-cleaner="fakeroot debian/rules clean"
We have not yet decided on how to deal with patches in upstream (this topic is under discussion). Possibilities include direct commits in the master branch, use of TopGit and quilt-serialized patches, and raw quilt or dpatch.
Patches can be serialized using Git. Two tools are used to apply and save the patches in debian/patches/series.
dom-apply-patches: Creates the branch patch-queue and checkout it. Then, it applies all patches listed in debian/patches/series.
dom-save-patches:
Move back to branch master
Save all patches present in branch patch-queue (where each commit represents a patch to upstream) in debian/patches/
Update debian/patches/series
Remove branch patch-queue
The branch patch-queue is used only locally and should never be pushed.
(Hopefully) All OCaml-related Debian packages are maintained using a centralized Subversion (SVN for short) repository. This practice reduce the efforts needed to contribute work inside The Debian OCaml Task Force and, in case of need, provides a place where to massively perform changes to all OCaml-related Debian packages.
Nonetheless, Debian users can benefit knowing we are using a SVN repository (they can for instance subscribe to the RSS feed for changes or have a place where to look for finding patches corresponding to bugs tagged "pending" in the BTS).
For this reason it is recommended to add the
Vcs-Svn
and Vcs-Browser
fields to the
debian/control
of packages maintained in
The Debian OCaml Task Force SVN repository. Its name specifies that we are
using Subversion as our Version Control System (VCS);
their values are the URLs pointing to the package's trunk directory and to
a browsable view of the same directory. See Bug
#391023 (which contains the forthcoming text for the Debian
Developer's Reference) for more information about these fields.
The general scheme for using the fields are thus:
Vcs-Svn: svn://svn.debian.org/svn/pkg-ocaml-maint/trunk/packages/PACKAGE_NAME Vcs-Browser: http://svn.debian.org/wsvn/pkg-ocaml-maint/trunk/packages/PACKAGE_NAME/trunk/
Example 3.2. Usage example of the Vcs-* fields, from the findlib package
Source: findlib Section: devel Priority: optional Maintainer: Stefano Zacchiroli <zack@debian.org> Build-Depends: debhelper (>> 4.0.0), ocaml (>= 3.09.2), m4, gawk | awk, dpatch, cdbs Standards-Version: 3.7.2 Vcs-Svn: svn://svn.debian.org/svn/pkg-ocaml-maint/trunk/packages/findlib Vcs-Browser: http://svn.debian.org/wsvn/pkg-ocaml-maint/trunk/packages/findlib/trunk/ Package: ocaml-findlib Section: devel Architecture: any Depends: ocaml-${F:OCamlABI}, ${shlibs:Depends}, ${misc:Depends} Description: Management tool for OCaml programming language libraries ...
You can obtain a copy of debian-ocaml-maint SVN repository by
svn co svn+ssh://svn.debian.org/svn/pkg-ocaml-maint
You must be member of the Debian OCaml Task Force in order to have write access to the repository.
We keep all files of the debian subdirectory under SVN control, and
upstream only as a compressed tarball. The rationale behind this is
that changes to upstream files should be managed by the dpatch patch
manager. Hence, all the diffs to upstream files are kept in a
subdirectory of debian/
, and it is not necessary to manage upstream on
file-by-file basis.
The structure of the pkg-ocaml-maint SVN repository is as follows, where
generic names are indicated in square brackets [ .. ]
, and where the
contents of subdirectories not directly relevant for package management
are not detailed:
tags packages [package1] [version1] [version2] ... [package2] [version1] ... ... projects test trunk packages [package1] trunk debian tarballs [upstream-tarball-version1] [upstream-tarball-version2] ... [package2] ... policy projects tools
Place yourself in the directory trunk/packages
of your working copy of
the SVN repository. Create a directory with the same name as your
source package (let's say, my-package), and subdirectories tarballs
and trunk
. Put the current upstream tarball in tarballs
, and the
current debian directory with all its relevant files in trunk
. This
should now look like this:
trunk/packages/my_package tarballs my_package_1.2.3.orig.tar.gz trunk debian changelog control copyright patches 00_list 01_patch1.dpatch ... ...
If everything is in order you can do a svn add my_package from the trunk/packages
directory, and eventually svn commit.
Please see the svn-buildpackage documentation for complete information. The important issues here are:
Since we keep upstream as a tarball we have to use svn-buildpackage in so-called merge mode. This means that, before compiling the package, the debianized source tree is constructed by untarring the orig tarball, and then merging the contents of the trunk subdirectory in it.
The structure of our SVN repository is not among the default structures of svn-buildpackage. Hence, we have to override the default location of some directories.
Place yourself in trunk/packages/my_packages/trunk
, and do the following:
svn propset mergeWithUpstream 1 debian.
This registers the property "mergeWithUpstream" with the current
directory, such that svn-buildpackage knows
that it has to use merge mode as explained above.
Create a file debian/svn-deblayout
with the following contents:
tagsUrl=svn+ssh://svn.debian.org/svn/pkg-ocaml-maint/tags/packages/my_package
Remember that "my_package" has to be replaced by the name of your actual package. svn-buildpackage will not include this file in the source package when actually building the package.
If you tried svn-buildpackage before writing your debian/svn-deblayout
remember
to delete .svn/deb-layout
, since svn-buildpackages caches here the content
of svn-deblayout
(that would be empty in this case) and will ignore
your debian/svn-deblayout
.
Please refer to the svn-builpackage documentation for more complete information. Here is just a quick guide.
All options, except those starting on --svn
, are passed to
dpkg-buildpackage. Hence, basic usage should be something like this
(from the trunk/packages/my_package/trunk
directory): svn-buildpackage -rfakeroot -uc -us.
svn-buildpackage will complain when your copy
of the debian directory is not in sync with the repository. You may use
the option --svn-ignore-new
to override this behaviour.
The package will be build in the directory
../build-area
.
If your package is ready for upload you may use the --svn-tag
option
for the final build. This will put a tag in the svn-repository on the
current version, and add a new entry in the changlog to start working
on the upcomming next version: svn-buildpackage --svn-tag.
Provided you have commited all your changes to the svn repository, this
will after a successful build of the package create a tag for the current
version in tags/packages/my_package
. The tagging is done directly in the
SVN repository.
Some useful aliases taken from the svn-buildpackage HOWTO:
alias svn-b='svn-buildpackage -rfakeroot --svn-dont-clean -us -uc --svn-ignore' alias svn-bt='svn-buildpackage -rfakeroot --svn-lintian --svn-dont-clean --svn-tag'
The former (svn-b) is to be used for test builds, while you are working on your package; while the latter (svn-bt) is to be used at the end, after you commit your changes and just before uploading a new version of the package to the debian archive.
Adding -k<your gpg id> to the svn-bt alias may also be useful when working on collaboratively maintained packages:
alias svn-bt='svn-buildpackage -rfakeroot -k<gpgid> --svn-lintian --svn-dont-clean --svn-tag'
dpatch will work properly at package build time with the SVN
structure described above since all of the build process will be
carried out in a fresh directory. However, invoking
debian/rules
with the "clean" target in
the trunk/
directory will fail since
dpatch is unable to de-apply patches. Passing
--svn-dont-clean
to
svn-buildpackage fixes this
misbehaviour (aliases suggested above already include this
flag).
If you want to use dpatch-edit-patch to handle patches, you will need to invoke
it in "debian only mode" (-b
flag, see man dpatch-edit-patch) and to tell him
where to find the upstream tarball. Adding the following line to your
~/.dpatch.conf
will be enough:
conf_origtargzpath=../tarballs
The Debian OCaml Task Force's website: http://pkg-ocaml-maint.alioth.debian.org/ (it's an Alioth project)
The Debian OCaml Task Force's mailing list: debian-ocaml-maint@lists.debian.org ( archives)
The Debian OCaml Task Force wiki page http://wiki.debian.org/Teams/OCamlTaskForce/