代码拉取完成，页面将自动刷新
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>A guide to robotpkg</title>
</head>
<style type="text/css">
/* --- preamble ------------------------------------------------------------ */
body {
color: #444;
background: #fff;
font: normal normal normal small/1.5em Verdana, sans-serif;
font-size-adjust: none;
font-stretch: normal;
text-align: center;
min-width: 50em;
}
a:link, a:visited {
color: #660403;
font-weight: normal;
text-decoration: none;
}
a:hover {
color: #e90017;
text-decoration: underline;
}
div.p {
margin: 1em 0;
}
table td {
border-style: none;
padding: 0 4ex;
}
table td#hline {
border-top: 1px solid #ccc;
}
table, table tr {
border: 1px solid #ccc;
}
#content {
text-align: left;
width: 50em;
margin-left: auto;
margin-right: auto;
}
#frontmatter, #mainmatter {
width: 90%;
text-align: justify;
}
#preamble h1 {
font-size: 300%;
line-height: 120%;
border-bottom: 1px solid #ccc;
padding-bottom: 1ex;
}
/* --- front matter -------------------------------------------------------- */
#frontmatter h1 {
width: 111%;
font-size: 250%;
line-height: 150%;
margin: 5ex 0 1ex 0;
}
#frontmatter a {
font-size: 125%;
line-height: 1.5em;
}
/* --- main matter --------------------------------------------------------- */
/* chapters */
#mainmatter h1 {
width: 111%;
text-align: right;
font-size: 250%;
line-height: 150%;
margin: 10ex 0 2ex 0;
border-bottom: 1px solid #ccc;
}
#mainmatter h1 > a {
font-size: 150%;
margin: 0;
padding-right: 10%
}
#mainmatter h2 {
font-size: 150%;
line-height: 150%;
margin: 4ex 0 1ex 0;
}
</style>
<body><div id="content">
<div id="preamble">
<div class="p"><!----></div>
<div class="p"><!----></div>
<h1 align="center">A guide to robotpkg </h1>
<h3 align="center">Anthony Mallet - <tt>[email protected]</tt> </h3>
<h3 align="center">October 9, 2017</h3>
<div class="p"><!----></div>
<div class="p"><!----></div>
</div><div id="frontmatter">
<div class="p"><!----></div>
<div class="small">Copyright © 2006-2011,2013 LAAS/CNRS.<br />
Copyright © 1997-2010 The NetBSD Foundation, Inc.<br />
All rights reserved.<br />
<div class="p"><!----></div>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
<div class="p"><!----></div>
<ol type="1">
<li> Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
<div class="p"><!----></div>
</li>
<li> Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
<div class="p"><!----></div>
</li>
</ol>
<div class="p"><!----></div>
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
</div>
<div class="p"><!----></div>
<h1>Contents </h1><a href="#tth_chAp1"
>1 Introduction</a><br />
<a href="#tth_sEc1.1"
>1.1 What is robotpkg?</a><br />
<a href="#tth_sEc1.2"
>1.2 Why robotpkg?</a><br />
<a href="#tth_sEc1.3"
>1.3 Supported platforms</a><br />
<a href="#tth_sEc1.4"
>1.4 Overview</a><br />
<a href="#tth_sEc1.5"
>1.5 Terminology</a><br />
<a href="#tth_sEc1.6"
>1.6 Roles involved in robotpkg</a><br />
<a href="#tth_sEc1.7"
>1.7 Typography</a><br />
<a href="#tth_chAp2"
>2 The robotpkg user's guide</a><br />
<a href="#tth_sEc2.1"
>2.1 Where to get robotpkg and how to keep it up-to-date</a><br />
<a href="#tth_sEc2.1.1"
>2.1.1 Getting the binary bootstrap kit</a><br />
<a href="#tth_sEc2.1.2"
>2.1.2 Getting robotpkg for source compilation</a><br />
<a href="#tth_sEc2.1.3"
>2.1.3 Keeping robotpkg up-to-date</a><br />
<a href="#tth_sEc2.2"
>2.2 Bootstrapping robotpkg</a><br />
<a href="#tth_sEc2.2.1"
>2.2.1 Bootstrapping via the binary kit</a><br />
<a href="#tth_sEc2.2.2"
>2.2.2 Bootstrapping from source</a><br />
<a href="#tth_sEc2.3"
>2.3 Using robotpkg</a><br />
<a href="#tth_sEc2.3.1"
>2.3.1 Building packages from source</a><br />
<a href="#tth_sEc2.3.2"
>2.3.2 Building packages from a repository checkout</a><br />
<a href="#tth_sEc2.3.3"
>2.3.3 Installing binary packages</a><br />
<a href="#tth_sEc2.3.4"
>2.3.4 Removing packages</a><br />
<a href="#tth_sEc2.3.5"
>2.3.5 Getting information about installed packages</a><br />
<a href="#tth_sEc2.3.6"
>2.3.6 Other administrative functions</a><br />
<a href="#tth_sEc2.3.7"
>2.3.7 Available <tt>make</tt> targets</a><br />
<a href="#tth_sEc2.4"
>2.4 Configuring robotpkg</a><br />
<a href="#tth_sEc2.4.1"
>2.4.1 Selecting build options</a><br />
<a href="#tth_sEc2.4.2"
>2.4.2 Selecting build alternatives</a><br />
<a href="#tth_sEc2.4.3"
>2.4.3 Defining collections of packages</a><br />
<a href="#tth_sEc2.4.4"
>2.4.4 Package specific configuration variables</a><br />
<a href="#tth_sEc2.4.5"
>2.4.5 General configuration variables</a><br />
<a href="#tth_sEc2.4.6"
>2.4.6 Variables affecting the build process</a><br />
<a href="#tth_sEc2.4.7"
>2.4.7 Additional flags to the compiler</a><br />
<a href="#tth_sEc2.5"
>2.5 Creating binary packages for everything</a><br />
<a href="#tth_sEc2.5.1"
>2.5.1 Initial setup</a><br />
<a href="#tth_sEc2.5.2"
>2.5.2 Running bulk builds</a><br />
<a href="#tth_sEc2.5.3"
>2.5.3 Generating pretty reports</a><br />
<a href="#tth_sEc2.5.4"
>2.5.4 Automated bulk builds</a><br />
<a href="#tth_chAp3"
>3 The robotpkg developer's guide</a><br />
<a href="#tth_sEc3.1"
>3.1 Package files, directories and contents</a><br />
<a href="#tth_sEc3.1.1"
>3.1.1 Makefile</a><br />
<a href="#tth_sEc3.1.2"
>3.1.2 distinfo</a><br />
<a href="#tth_sEc3.1.3"
>3.1.3 PLIST</a><br />
<a href="#tth_sEc3.1.4"
>3.1.4 patches/*</a><br />
<a href="#tth_sEc3.2"
>3.2 General operation</a><br />
<a href="#tth_sEc3.2.1"
>3.2.1 Adding build options to a package</a><br />
<a href="#tth_sEc3.2.2"
>3.2.2 Customizing the PLIST</a><br />
<a href="#tth_sEc3.2.3"
>3.2.3 Customizing the semi-automatic PLIST generation</a><br />
<a href="#tth_sEc3.2.4"
>3.2.4 Incrementing versions when fixing an existing package</a><br />
<a href="#tth_sEc3.2.5"
>3.2.5 Substituting variable text in the package files</a><br />
<a href="#tth_sEc3.3"
>3.3 The build phase</a><br />
</div><div id="mainmatter">
<div class="p"><!----></div>
<a id="tth_chAp1"></a><h1>
1 <br />Introduction</h1>
<a id="chapter:introduction">
</a>
<div class="p"><!----></div>
<a id="tth_sEc1.1"></a><h2>
1.1 What is robotpkg?</h2>
<div class="p"><!----></div>
The robotics research community has always been developing a lot of software,
in order to illustrate theoretical concepts and validate algorithms on board
real robots. A great amount of this software was made freely available to the
community, especially for Unix-based systems, and is usually available in form
of the source code. Therefore, before such software can be used, it needs to be
configured to the local system, compiled and installed. This is exactly what
The Robotics Packages Collection (robotpkg) does. robotpkg also has some basic
commands to handle binary packages, so that not every user has to build the
packages for himself, which is a time-costly, cumbersome and error-prone task.
<div class="p"><!----></div>
The robotpkg project was initiated in the <a href="http://www.laas.fr/">Laboratory
for Analysis and Architecture of Systems</a> (CNRS/LAAS), France. The motivation
was, on the one hand, to ease the software maintenance tasks for the robots
that are used there. On the other hand, roboticists at CNRS/LAAS have always
fostered an open-source development model for the software they were
developing. In order to help people working with the laboratory to get the
LAAS software running outside the laboratory, a package management system was
necessary.
<div class="p"><!----></div>
Although robotpkg was an innovative project in the robotics community (it
started in 2006), a lot of general-purpose software packages management systems
were readily available at this time for a great variety of Unix-based systems.
The main requirements that we wanted robotpkg to fullfill were listed and the
best existing package management system was chosen as a starting point. The
biggest requirement was the capacity of the system to adapt to the nature of
the robotic software, being available mostly in form of source code only (no
binary packages), with unfrequent stable releases. robotpkg had thus to deal
mostly with source code and automate the compilation of the packages. The
system chosen as a starting point was <a href="http://www.pkgsrc.org">The NetBSD
Packages Collection</a> (pkgsrc). robotpkg can be considered as a fork of this
project and it is still very similar to pkgsrc in many points, although some
simplifications were made in order to provide a tool geared toward people that
are not computer scientists but roboticists.
<div class="p"><!----></div>
Due to its origins, robotpkg provides many packages developed at LAAS. It is
however not limited to such packages and contains, in fact, quite some other
software useful to roboticists. Of course, robotpkg is not meant to be a
general purpose packaging system (although there would be no technical
restriction to this) and will never contain widely available packages that can
be found on any modern Unix distribution. Yet, robotpkg currently contains
roughly one hundred and fifty packages, including:
<div class="p"><!----></div>
<ul>
<li> architecture/genom - The LAAS Generator of Robotic Components
<div class="p"><!----></div>
</li>
<li> architecture/openrtm - The robotic distributed middleware from AIST, Japan
<div class="p"><!----></div>
</li>
<li> middleware/yarp - The "other", yet famous, robot platform
<div class="p"><!----></div>
</li>
<li> ...just to name a few.
<div class="p"><!----></div>
</li>
</ul>
<div class="p"><!----></div>
<a id="tth_sEc1.2"></a><h2>
1.2 Why robotpkg?</h2>
<div class="p"><!----></div>
robotpkg provides the following key features:
<div class="p"><!----></div>
<ul>
<li> Easy building of software from source as well as the creation and
installation of binary packages. The source and latest patches are retrieved
from a master download site, checksum verified, then built on your system.
<div class="p"><!----></div>
</li>
<li> All packages are installed in a consistent directory tree, including
binaries, libraries, man pages and other documentation.
<div class="p"><!----></div>
</li>
<li> Package dependencies, including when performing package updates, are
handled automatically.
<div class="p"><!----></div>
</li>
<li> The installation prefix, acceptable software licenses and build-time
options for a large number of packages are all set in a simple, central
configuration file.
<div class="p"><!----></div>
</li>
<li> The entire framework source (not including the package distribution
files themselves) is freely available under a BSD license, so you may extend
and adapt robotpkg to your needs, like robotpkg was adapted from pkgsrc.
<div class="p"><!----></div>
</li>
</ul>
<div class="p"><!----></div>
One question often asked by people is "why was robotpkg forked from pkgsrc
instead of integrating the packages into pkgsrc?". This is indeed a very good
question and the following paragraphs try to answer it.
<div class="p"><!----></div>
First, robotpkg is not meant to be a replacement for the system's package
management tool (it does not superseeds pkgsrc, dpkg, macports etc.). The goal
is to package software that is not widely available on a platform, and which is
mostly "lab software" (generally of lesser quality than widely available
software). Those packages change (a lot) more often, and more
drastically. Thus, robotpkg is a little bit closer to a "development" tool than
pkgsrc. Other "system packages" are correctly handled by a number of
packaging tools, and there is no need for a new tool.
<div class="p"><!----></div>
Currently, pkgsrc mixes both infrastructure and packages descriptions
themselves. For someone working on e.g. Linux, checking-out
the whole pkgsrc tree would be cumbersome: it would be redundant with the base
Linux package system, plus it would be difficult to isolate the specific
robotic packages from the rest (the rest usually being available in the base
system). robotpkg currently suffers from the same symptom: this may change in
the future if the need for several package repositories becomes blatant.
<div class="p"><!----></div>
robotpkg provides a number of features not available in pkgsrc (and probably
not really useful to pkgsrc either). The most important feature is to be able
to detect "system packages", that are considered as ëxternal software not in
robotpkg but usually available on a unix system". pkgsrc has a similar system
but much more limited - to a few base packages only. This is so because pkgsrc
is a full-fledged package system. Thus, it aims at being self contained, while
robotpkg does not.
<div class="p"><!----></div>
Finally, there are a number of additions/changes to the pkgsrc infrastructure
that correspond to legitimate users requests and the specifc workflow in which
robotpkg is used. For instance, robotpkg provides the possibility to generate
an archive of a package from a specific tag in a source repository "on the
fly" or just bypass the archive generation and work directly from the source
repository to install the software. This later workflow is not encouraged, but
it is convenient to quickly test a -current version of some software to see if
it causes any problem. Those features could be ported back to pkgsrc if the
pkgsrc team would find them useful. In the meantime, robotpkg provides a
good testbed for them.
<div class="p"><!----></div>
Still, robotpkg directly uses many of the pkgsrc tools unchanged and the binary
packages are fully compatible.
<div class="p"><!----></div>
<a id="tth_sEc1.3"></a><h2>
1.3 Supported platforms</h2>
<div class="p"><!----></div>
robotpkg consists of a source distribution. After retrieving the required
source, you can be up and running with robotpkg in just minutes!
<div class="p"><!----></div>
robotpkg does not have much requirements by itself and it can work on a wide
variety of systems as long as they provide a GNU-make utility, a working
C-compiler and a small, reasonably standard subset of Unix commands (like sed,
awk, find, grep ...). However, individual packages might have their specific
requirements. The following platforms have been reported to be supported
reasonably well:
<div class="p"><!----></div>
<div style="text-align:center">
<table border="1" class="tabular">
<tr><td align="center">Platform </td><td align="center">Version
</td></tr><tr><td id="hline" colspan=0></td></tr>
<tr><td align="center">Fedora </td><td align="center">25 or above</td></tr>
<tr><td align="center">Ubuntu </td><td align="center">12.04 or above</td></tr>
<tr><td align="center">Debian </td><td align="center">7 or above</td></tr>
<tr><td align="center">NetBSD </td><td align="center">6 or above</td></tr>
<tr><td align="center">Darwin </td><td align="center">Partial support - infrastructure works, individual packages may not</td></tr></table>
</div>
<div class="p"><!----></div>
Any other Unix-like platform should usually work.
<div class="p"><!----></div>
<a id="tth_sEc1.4"></a><h2>
1.4 Overview</h2>
<div class="p"><!----></div>
This document is divided into three parts. <a href="#chapter:user">The first one</a>
describes how one can use one of the packages in the Robotics Package
Collection, either by installing a precompiled binary package, or by building
one's own copy using robotpkg. <a href="#chapter:developer">The second part</a>
explains how to prepare a package so it can be easily built by other users
without knowing about the package's building details.
<a href="#chapter:internal">The third part</a> is intended for those who want to
understand how robotpkg is implemented.
<div class="p"><!----></div>
<a id="tth_sEc1.5"></a><h2>
1.5 Terminology</h2>
<div class="p"><!----></div>
Here is a description of all the terminology used within this document.
<div class="p"><!----></div>
<dl>
<dt><b>Package</b></dt>
<dd> A set of files and building instructions that describe what's
necessary to build a certain piece of software using robotpkg. Packages are
traditionally stored under <tt>/opt/robotpkg</tt>.</dd>
<dt><b>robotpkg</b></dt>
<dd> This is the The Robotics Package Collection. It handles
building (compiling), installing, and removing of packages.</dd>
<dt><b>Distfile</b></dt>
<dd> This term describes the file or files that are provided by
the author of the piece of software to distribute his work. All the changes
necessary to build are reflected in the corresponding package. Usually the
distfile is in the form of a compressed tar-archive, but other types are
possible, too. Distfiles are usually stored below <tt>
/opt/robotpkg/distfiles</tt>.</dd>
<dt><b>Precompiled/binary package</b></dt>
<dd> A set of binaries built with robotpkg from
a distfile and stuffed together in a single <tt>.tgz</tt> file so it can be
installed on machines of the same machine architecture without the need to
recompile. Packages are usually generated in <tt>/opt/robotpkg/packages</tt>.
<div class="p"><!----></div>
Sometimes, this is referred to by the term "package" too, especially in
the context of precompiled packages.</dd>
<dt><b>Program</b></dt>
<dd> The piece of software to be installed which will be
constructed from all the files in the distfile by the actions defined in the
corresponding package.</dd>
</dl>
<div class="p"><!----></div>
<a id="tth_sEc1.6"></a><h2>
1.6 Roles involved in robotpkg</h2>
<div class="p"><!----></div>
<dl>
<dt><b>robotpkg users</b></dt>
<dd> The robotpkg users are people who use the packages
provided by robotpkg. Typically they are student working in robotics. The
usage of the software that is <em>inside</em> the packages is not covered by
the robotpkg guide.
<div class="p"><!----></div>
There are two kinds of robotpkg users: Some only want to install pre-built
binary packages. Others build the robotpkg packages from source, either for
installing them directly or for building binary packages themselves. For
robotpkg users, <a href="#chapter:user">Part <a href="#chapter:user">2</a></a> should provide
all necessary documentation.</dd>
<dt><b>package maintainers</b></dt>
<dd> A package maintainer creates packages as
described in <a href="#chapter:developer">Part <a href="#chapter:developer">3</a></a>.</dd>
<dt><b>infrastructure developers</b></dt>
<dd> These people are involved in all those
files that live in the <tt>mk/</tt> directory and below. Only these people
should need to read through
<a href="#chapter:internal">Part </a>, though others might be
curious, too.</dd>
</dl>
<div class="p"><!----></div>
<a id="tth_sEc1.7"></a><h2>
1.7 Typography</h2>
<div class="p"><!----></div>
When giving examples for commands, shell prompts are used to show if the
command should/can be issued as root, or if "normal" user privileges are
sufficient. We use a <tt>#</tt> for root's shell prompt, and a <tt>%</tt> for
users' shell prompt, assuming they use the C-shell or tcsh.
<div class="p"><!----></div>
<a id="tth_chAp2"></a><h1>
2 <br />The robotpkg user's guide</h1>
<a id="chapter:user">
</a>
<div class="p"><!----></div>
Basically, there are two ways of using robotpkg. The first is to only install
the package tools and to use binary packages that someone else has prepared.
The second way is to install the programs from source. Then you are able to
build your own packages, and you can still use binary packages from someone
else. Sections in this document will detail both approaches where appropriate.
<div class="p"><!----></div>
<div class="p"><!----></div>
<a id="tth_sEc2.1"></a><h2>
2.1 Where to get robotpkg and how to keep it up-to-date</h2> <a id="section:getting">
</a>
<div class="p"><!----></div>
Before you download and extract the files, you need to decide where you want to
extract them and where you want robotpkg to install packages. By defaut, the
<tt>/opt/openrobots</tt> directory is used. In the rest of this document, the
installation path is called the <em>prefix</em>.
<div class="p"><!----></div>
<tt>robotpkg</tt> will <em>never</em> require administration privileges by itself.
We thus recommend that you do not install or run robotpkg as the root user. If
something ever goes really wrong, it might go less wrong if it is not running
as root. If you want to install to the default location <tt>/opt/openrobots</tt>,
we recommend that you create this directory owned by a regular user.
<div class="p"><!----></div>
Creating or using <tt>/opt/openrobots</tt> typically requires administration (<em>
a.k.a.</em> "<tt>root</tt>") privileges. If you don't have such privileges (or if
you want to install to a different location), you have to unpack the sources
and install the binary packages in another prefix. If you don't have any
special administration rights on the target machine, a safe bet is to choose
the <tt>$HOME/openrobots</tt> location, as the <tt>$HOME</tt> directory will
always be writable by yourself.
<div class="p"><!----></div>
Any prefix will work, but please note that you should choose an installation
path which is dedicated to robotpkg packages and not shared with other programs
(e.g., we do not recommend to use a prefix of <tt>/usr</tt>). Also, you should
not try to add any of your own files or directories (such as <tt>src/</tt>) below
the prefix tree. This will prevent possible conflicts between programs and
other files installed by the package system and whatever else may have been
installed there.
<div class="p"><!----></div>
Finally, the installation path shall not contain white-space or other
characters that are interpreted specially by the shell and some other programs:
use only letters, digits, underscores and dashes.
<div class="p"><!----></div>
The rest of this document will assume that you are using <tt>/opt/openrobots</tt>
as the prefix. You should adapt this path to whatever prefix you choosed.
<div class="p"><!----></div>
<a id="tth_sEc2.1.1"></a><h3>
2.1.1 Getting the binary bootstrap kit</h3>
<div class="p"><!----></div>
At the moment, the binary bootstrap kit is not available. Please get the <tt>
robotpkg</tt> sources as described in the next section.
<div class="p"><!----></div>
<a id="tth_sEc2.1.2"></a><h3>
2.1.2 Getting robotpkg for source compilation</h3>
<div class="p"><!----></div>
<tt>robotpkg</tt> sources are distributed <em>via</em> the
<a href="http://git-scm.com/"><tt>git</a></tt> software content management system. <tt>
git</tt> will probably be readily available on your system but if you don't have it
installed or if you are unsure about it, contact your local system
administrator.
<div class="p"><!----></div>
There are two download methods: the anonymous one and the authenticated
one:
<div class="p"><!----></div>
<ul>
<li> Anonymous download is the recommended method if you don't intend to
work on the robotpkg infrastructure itself, nor commit any changes or
packages additions back to the robotpkg main repository. Furthermore, the
possibility to send contributions via patches is still open.
<div class="p"><!----></div>
As your regular user, simply run in a shell:
<div class="p"><!----></div>
<pre>
% cd /opt/openrobots
% git clone git://git.openrobots.org/robots/robotpkg
% # or
% git clone https://git.openrobots.org/robots/robotpkg.git
</pre>
<div class="p"><!----></div>
</li>
<li> Authenticated download requires a valid login on the main robotpkg
repository, and will give you full commit access to this repository. Simply
run the following:
<div class="p"><!----></div>
<pre>
% cd /opt/openrobots
% git clone ssh://[email protected]/robots/robotpkg
</pre>
<div class="p"><!----></div>
</li>
</ul>
<div class="p"><!----></div>
<a id="tth_sEc2.1.3"></a><h3>
2.1.3 Keeping robotpkg up-to-date</h3>
<div class="p"><!----></div>
<tt>robotpkg</tt> is a living thing: updates to the packages are made
perdiodicaly, problems are fixed, enhancements are developed... If you
downloaded the robotpkg sources via git, you should keep it up-to-date so that
you get the most recent packages descriptions. This is done by running <tt>
git pull</tt> in the robotpkg source directory:
<div class="p"><!----></div>
<pre>
% cd /opt/openrobots/robotpkg
% git pull
</pre>
<div class="p"><!----></div>
When you update robotpkg, the git program will only touch those files that are
registered in the git repository. That means that any packages that you created
on your own will stay unmodified. If you change files that are managed by git,
later updates will try to merge your changes with those that have been done by
others. See the <tt>git-pull</tt> manual for details.
<div class="p"><!----></div>
If you want to be informed of package additions and other updates, a public
mailing list is available for your reading pleasure. Go to
<a href="https://sympa.laas.fr/sympa/info/robotpkg"><tt>https://sympa.laas.fr/sympa/info/robotpkg</tt></a> for more information and
subscription.
<div class="p"><!----></div>
<a id="tth_sEc2.2"></a><h2>
2.2 Bootstrapping robotpkg</h2> <a id="section:bootstrapping">
</a>
<div class="p"><!----></div>
Once you have downloaded the robotpkg sources or the binary bootstrap kit as
described in <a href="#section:getting">Section <a href="#section:getting">2.1</a></a>, a minimal
set of the administrative package management utilities must be installed on
your system before you can use robotpkg. This is called the "bootstrap
phase" and should be done only once, the very first time you download
robotpkg.
<div class="p"><!----></div>
<a id="tth_sEc2.2.1"></a><h3>
2.2.1 Bootstrapping via the binary kit</h3>
<div class="p"><!----></div>
At the moment, the binary bootstrap kit is not available. Please bootstrap <tt>
robotpkg</tt> as described in the next section.
<div class="p"><!----></div>
<a id="tth_sEc2.2.2"></a><h3>
2.2.2 Bootstrapping from source</h3>
<div class="p"><!----></div>
You will need a working C compiler and the GNU-make utility version 3.81 or
later. If you have extracted the robotpkg archive into the standard <tt>
/opt/openrobots/robotpkg</tt> location, installing the bootstrap kit from source
should then be as simple as:
<div class="p"><!----></div>
<pre>
% cd /opt/openrobots/robotpkg/bootstrap
% ./bootstrap
</pre>
<div class="p"><!----></div>
This will install various utilities into <tt>/opt/openrobots/sbin</tt>.
<div class="p"><!----></div>
Should you prefer another installation path, you could use the <tt>--prefix</tt>
option to change the default installation prefix. For instance, configuring
robotpkg to install programs into the openrobots directory in your home
directory can be done like this:
<div class="p"><!----></div>
<pre>
% cd robotpkg/bootstrap
% ./bootstrap --prefix=${HOME}/openrobots
</pre>
<div class="p"><!----></div>
<b>After the bootstrap script has run, a message indicating the success
should be displayed. If you choosed a non-standard installation path, read
this message carefuly</b>, as it contains instructions that you have to follow in
order to setup your shell environment correctly. These instructions are
described in the next section.
<div class="p"><!----></div>
<h4>Configuring your environment</h4>
<div class="p"><!----></div>
If you configured robotpkg, during the bootstrap phase, to install to some
other location than <tt>/opt/openrobots</tt>, you have to setup manually your
shell environment so that it contains a few variables holding the installation
path. Assuming you invoked bootstrap with <tt>-prefix=/path/to/openrobots</tt>,
you have two options that are compatible with each other:
<div class="p"><!----></div>
<ul>
<li> Add the directory <tt>/path/to/openrobots/sbin</tt> to your <tt>PATH</tt>
variable. robotpkg will then be able to find its administrative tools
automatically and from that recover other configuration information. This is
the preferred method.
<div class="p"><!----></div>
</li>
<li> Create the environment variable <tt>ROBOTPKG_BASE</tt> and set its value
to <tt>/path/to/openrobots</tt>. robotpkg will look for this variable first,
so it takes precedence over the first method. This is the method you have
to choose if you have configured several instances of robotpkg in your
system. This is ony useful in some circumstances and is not normally needed.
<div class="p"><!----></div>
</li>
</ul>
<div class="p"><!----></div>
If you don't know how to setup environment variables permanently in your
system, please refer to your shell's manual or contact your local system
administrator.
<div class="p"><!----></div>
<h4>The bootstrap script usage</h4>
<div class="p"><!----></div>
The <tt>bootstrap</tt> script will by default install the package administrative
tools in <tt>/opt/openrobots/sbin</tt>, use <tt>gcc</tt> as the C compiler and <tt>
make</tt> as the GNU-make program. This behaviour can be fine-tuned by using the
following options:
<div class="p"><!----></div>
<dl>
<dt><b><tt>--prefix <path></b></dt>
<dd> will select the prefix location where
programs will be installed in.</tt></dd>
<dt><b><tt>--sysconfdir <path></b></dt>
<dd> defaults to <tt><prefix>/etc</tt>. This is the
path to the robotpkg configuration file. Other packages configuration files
(if any) will also be stored in this directory.</tt></dd>
<dt><b><tt>--pkgdbdir <path></b></dt>
<dd> defaults to <tt><prefix>/var/db/pkg</tt>. This
is the path to the package database directory where robotpkg will do its
internal bookkeeping.</tt></dd>
<dt><b><tt>--compiler <program></b></dt>
<dd> defaults to <tt>gcc</tt>. Use this option if
you want to use a different C compiler.</tt></dd>
<dt><b><tt>--make <program></b></dt>
<dd> defaults to <tt>make</tt>. Use this option if you
want to use a different make program. This program should be compatible with
GNU-make.</tt></dd>
<dt><b><tt>--help</b></dt>
<dd> displays the <tt>bootstrap</tt> usage. The comprehensive
list of recognized options will be displayed.</tt></dd>
</dl>
<div class="p"><!----></div>
<a id="tth_sEc2.3"></a><h2>
2.3 Using robotpkg</h2>
<div class="p"><!----></div>
After obtaining <tt>robotpkg</tt> , the <tt>robotpkg</tt> directory now contains a set of
packages, organized into categories. You can browse the online index of
packages, or run <tt>make index</tt> from the <tt>robotpkg</tt> directory to build
local <tt>index.html</tt> files for all packages, viewable with any web browser
such as <tt>lynx</tt> or <tt>firefox</tt>.
<div class="p"><!----></div>
<tt>robotpkg</tt> is essentially based on the <tt>make(1)</tt> program. All actions are
triggered by invoking <tt>make</tt> with the proper target. The following sections
document the most useful ones and
<a href="#section:using:targets">section <a href="#section:using:targets">2.3.7</a></a> recaps a more
comprehensive list.
<div class="p"><!----></div>
<a id="tth_sEc2.3.1"></a><h3>
2.3.1 Building packages from source</h3>
<div class="p"><!----></div>
The first step for building a package is downloading the <em>distfiles</em>
(i.e. the unmodified source). If they have not yet been downloaded, <tt>robotpkg</tt>
will fetch them automatically and place them in the <tt>robotpkg/distfiles</tt>
directory.
<div class="p"><!----></div>
Once the software has been downloaded, any patches will be applied and the
package will be compiled for you. This may take some time depending on your
computer, and how many other packages the software depends on and their compile
time.
<div class="p"><!----></div>
For example, type the following commands at the shell prompt to build the
robotpkg documentation package:
<div class="p"><!----></div>
<pre>
% cd /opt/openrobots/robotpkg
% cd doc/robotpkg
% make
</pre>
<div class="p"><!----></div>
The next stage is to actually install the newly compiled package onto your
system. While you are still in the directory for whatever package you are
installing, you can do this by entering:
<div class="p"><!----></div>
<pre>
% make install
</pre>
<div class="p"><!----></div>
Installing the package on your system does not require you to be root (except
for a few specific packages). However, if you bootstraped with a prefix for
which you don't have writing permissions, <tt>robotpkg</tt> has a <span class="roman">
just-in-time-sudo</span> feature, which allows you to become <tt>root</tt> for the
actual installation step.
<div class="p"><!----></div>
That's it, the software should now be installed under the prefix of the
packages tree - <tt>/opt/openrobots</tt> by default - and setup for use.
<div class="p"><!----></div>
You can now enter:
<div class="p"><!----></div>
<pre>
% make clean
</pre>
<div class="p"><!----></div>
to remove the compiled files in the work directory, as you shouldn't need them
any more. If other packages were also added to your system (dependencies) to
allow your program to compile, you can also tidy these up with the command:
<div class="p"><!----></div>
<pre>
% make clean-depends
</pre>
<div class="p"><!----></div>
Since the three tasks of building, installing and cleaning correspond to the
typical usage of <tt>robotpkg</tt> , a helper target doing all these tasks exists and is
called <tt>update</tt>. Thus, to intall a package with a single command, you can
simply run:
<div class="p"><!----></div>
<pre>
% make update
</pre>
<div class="p"><!----></div>
In addition, <tt>make update</tt> will also recompile all the installed packages
that were depending on the package that you are updating. This can be quite
time consuming if you are updating a low-level package. Also, note that all
packages that depend on the package you are updating will be deinstalled
first and unavailable in your system until all packages are recompiled and
reinstalled.
<div class="p"><!----></div>
<div class="p"><!----></div>
Occasionally, people want to "look under the covers" to see what is going on
when a package is building or being installed. This may be for debugging
purposes, or out of simple curiosity. A number of utility values have been
added to help with this.
<div class="p"><!----></div>
<ol type="1">
<li> If you invoke the <tt>make</tt> command with <tt>PKG_DEBUG_LEVEL=1</tt>, then
a huge amount of information will be displayed. For example,
<div class="p"><!----></div>
<pre>
% make patch PKG_DEBUG_LEVEL=1
</pre>
<div class="p"><!----></div>
will show all the commands that are invoked, up to and including the
"patch" stage. Using <tt>PKG_DEBUG_LEVEL=2</tt> will give you even
more details.
<div class="p"><!----></div>
</li>
<li> If you want to know the value of a certain <tt>make</tt> definition, then
the <tt>VARNAME</tt> variable should be used, in conjunction with the <tt>
show-var</tt> target. e.g. to show the expansion of the <tt>make</tt> variable
<tt>LOCALBASE</tt>:
<div class="p"><!----></div>
<pre>
% make show-var VARNAME=LOCALBASE
</pre>
<div class="p"><!----></div>
</li>
</ol>
<div class="p"><!----></div>
<div class="p"><!----></div>
<div class="p"><!----></div>
<a id="tth_sEc2.3.2"></a><h3>
2.3.2 Building packages from a repository checkout</h3> <a id="section:using:checkout">
</a>
<div class="p"><!----></div>
Before building a package, <tt>robotpkg</tt> fetches the sources from the official(s)
download location(s), as instructed by the <tt>MASTER_SITES</tt> variable.
This is the standard and expected behaviour when you work with stable packages.
<div class="p"><!----></div>
Occasionally, though, it is useful to fetch a snapshot of the sources from a
development repository. For instance, one might want to quickly test a release
candidate of a package, or fix a simple bug and create a patch from the fix.
Whenever a package defines the <tt>MASTER_REPOSITORY</tt> variable, <tt>robotpkg</tt> is
able to temporarily work with the repository defined in this variable. At the
moment, <tt>cvs</tt>, <tt>svn</tt> and <tt>git</tt> repositories are supported.
<div class="p"><!----></div>
To enable this feature for a given package, you have to first instruct
<tt>robotpkg</tt> to work from a '<tt>checkout</tt>' (instead of the stable releases) by
doing '<tt>make checkout</tt>' in the package directory. For instance:
<div class="p"><!----></div>
<pre>
% cd robotpkg/foo/bar
% make checkout
</pre>
<div class="p"><!----></div>
This sets a permanent flag in the <em>working</em> directory of the package and
the <em>checkout</em> configuration option will be retained until the next '<tt>
make clean</tt>'. After a '<tt>make clean</tt>', the configuration option is set back
to its default and <tt>robotpkg</tt> will work again with stable releases. This option
is set on a <em>per</em> package basis only: configuring one package to work with
checkouts does not affect the behaviour of other packages.
<div class="p"><!----></div>
After a '<tt>make checkout</tt>' (and until a '<tt>make clean</tt>'), the package has
a regular checkout in its <em>working</em> subdirectory. You can thus manually
edit, commit, switch branches, etc. in the package sources, like in any other
repository, by first <tt>cd</tt>ing into the working directory, then using the
usual repository commands (<tt>cvs</tt>, <tt>svn</tt> or <tt>git</tt>).
<div class="p"><!----></div>
Of course, the individual <tt>robotpkg</tt> targets are still available from the
package entry in the robotpkg hierarchy. You can for instance <tt>'make
patch'</tt>, <tt>'configure'</tt>, <tt>'build'</tt>, <tt>'install'</tt> or <tt>'update'</tt> as
usual. Note that <tt>robotpkg</tt> is not exactly stateless, and this is most visible
when working with checkouts: for instance, after a successful <tt>'make
build'</tt>, you have to do <tt>'make rebuild'</tt> to force rebuilding if you have
modified the sources. The same holds for <tt>'configure'</tt> (do <tt>
'reconfigure'</tt>) or <tt>'install'</tt> (do 'reinstall', but since you cannot
install a package twice, you normally have to use <tt>'make replace'</tt> in the
particular case of reinstalling a package).
<div class="p"><!----></div>
The <tt>'clean'</tt> target is special, in that it removes the checkout
configuration option and all checkouted sources, including locally modified
sources. In order to prevent accidental deletion of precious files, you have to
confirm the cleanign with <tt>'clean confirm'</tt>, as in:
<div class="p"><!----></div>
<pre>
% make clean confirm
</pre>
<div class="p"><!----></div>
A final remark: we <em>STRONGLY DISCOURAGE</em> the use of robotpkg as a
development tool (i.e. using the <tt>'checkout'</tt> feature on a <em>regular</em>
basis), for at least two reasons:
<div class="p"><!----></div>
<ul>
<li> <tt>robotpkg</tt> is not designed for this: it will not really help you in
your daily development work, compared to the manual configuration
installation of the software. It will sometimes create even more trouble, by
ensuring that all the software depending on the checkouted software is
up-to-date, which is not necessarily something you want to do every time you
compile.
<div class="p"><!----></div>
</li>
<li> A checkout breaks the notion of 'release' and you loose all the
benefits from working with packages. In particular, you have no clear state
of what is installed: you cannot easily reproduce the situation of time T at
time T+n and don't know precisely who requires which version of what. It is
much more efficient and robust to release frequently a software in a
development phase, than using a <em>rolling release</em> approach.
<div class="p"><!----></div>
</li>
</ul>
<div class="p"><!----></div>
In our opinion, the <tt>'checkout'</tt> target use should be limited to testing a
release candidate or quickly fix a bug and create a patch from the fix, that
you commit upstream and put in the patches/ directory until the next release.
<div class="p"><!----></div>
<a id="tth_sEc2.3.3"></a><h3>
2.3.3 Installing binary packages</h3>
<div class="p"><!----></div>
At the moment, installing binary packages is not documented.
<div class="p"><!----></div>
<a id="tth_sEc2.3.4"></a><h3>
2.3.4 Removing packages</h3>
<div class="p"><!----></div>
To deinstall a package, it does not matter whether it was installed from source
code or from a binary package. The <tt>robotpkg_delete</tt> command does not
know it anyway. To delete a package, you can just run <tt>robotpkg_delete
<package-name></tt>. The package name can be given with or without version number.
Wildcards can also be used to deinstall a set of packages, for example <tt>
*genom*</tt> all packages whose name contain the word <tt>genom</tt>. Be sure to
include them in quotes, so that the shell does not expand them before <tt>
robotpkg_delete</tt> sees them.
<div class="p"><!----></div>
The <tt>-r</tt> option is very powerful: it removes all the packages that require
the package in question and then removes the package itself. For example:
<div class="p"><!----></div>
<pre>
% robotpkg_delete -r genom
</pre>
<div class="p"><!----></div>
will remove genom and all the packages that used it; this allows
upgrading the <tt>genom</tt> package.
<div class="p"><!----></div>
<a id="tth_sEc2.3.5"></a><h3>
2.3.5 Getting information about installed packages</h3>
<div class="p"><!----></div>
The <tt>robotpkg_info</tt> shows information about installed packages or binary
package files.
<div class="p"><!----></div>
<a id="tth_sEc2.3.6"></a><h3>
2.3.6 Other administrative functions</h3>
<div class="p"><!----></div>
The <tt>robotpkg_admin</tt> executes various administrative functions on the
package system.
<div class="p"><!----></div>
<a id="tth_sEc2.3.7"></a><h3>
2.3.7 Available <tt>make</tt> targets</h3> <a id="section:using:targets">
</a>
<div class="p"><!----></div>
The following targets are available in a package directory. They can be invoked
by running <tt>make <target></tt> after <tt>cd</tt>ing into some <tt>
robotpkg/category/package</tt>.
<div class="p"><!----></div>
<h4>Source manipulation</h4>
<dl>
<dt><b><tt>fetch</tt></b></dt>
<dd> Download the <tt>${DISTFILES}</tt>.</dd>
<dt><b><tt>extract</tt></b></dt>
<dd> Extract the contents of <tt>${DISTFILES}</tt> into the
work directory <tt>${WRKDIR}</tt>.</dd>
<dt><b><tt>patch</tt></b></dt>
<dd> Apply local patches available in <tt>${PATCHDIR}</tt>
(usually the <tt>patches</tt> directory in the package).</dd>
<dt><b><tt>checkout</tt></b></dt>
<dd> Extract the sources in <tt>${WRKDIR}</tt> from
<tt>${MASTER_REPOSITORY}</tt> instead of <tt>${MASTER_SITES}</tt>. This can
be used to fetch a not yet released version instead of the latest
release. This is mutually exclusive with the <tt>fetch</tt> and <tt>extract</tt>
targets. See
<a href="#section:using:checkout">section <a href="#section:using:checkout">2.3.2</a></a> for
details.</dd>
<dt><b><tt>configure</tt></b></dt>
<dd> Perform the necessary actions to configure the
sources. This may for instance involve running <tt>configure</tt> or <tt>
cmake</tt>. If no configuration is required, this step simply does nothing.</dd>
<dt><b><tt>build</tt></b></dt>
<dd> Or just <tt>make</tt>, the default target. It compiles the
package locally in <tt>${WRKDIR}</tt>.</dd>
<dt><b><tt>install</tt></b></dt>
<dd> Install the package into <tt>${PREFIX}</tt>. The package
is then available to the rest of the system. If an older version of the
package is installed and required by other packages, this target requires
confirmation. Otherwise, any older version of the package is first
deinstalled.</dd>
<dt><b><tt>replace</tt></b></dt>
<dd> Same as <tt>install</tt>, but does not remove packages
that depend on the replaced package. This saves some time, since already
installed package are not touched, but if the replaced package is
incompatible with the older version, you will run into trouble. Use with
care and when you know what you are doing.</dd>
<dt><b><tt>clean</tt></b></dt>
<dd> Tidy the work directory and removes <tt>${WRKDIR}</tt>. If
the package was extracted using <tt>checkout</tt>, this target requires
confirmation as it may delete locally modified files that will be lost.</dd>
<dt><b><tt>update</tt></b></dt>
<dd> This is a shortcut target for <tt>fetch</tt>, <tt>
extract</tt>, <tt>configure</tt>, <tt>build</tt>, <tt>install</tt> and <tt>clean</tt>. If
the package is already installed and up-to-date, the target asks for
confirmation.</dd>
</dl>
<div class="p"><!----></div>
<h4>Introspection</h4>
<dl>
<dt><b><tt>show-options</tt></b></dt>
<dd> Display the list of available alternatives (see
<a href="#section:configuring:alternatives">section <a href="#section:configuring:alternatives">2.4.2</a></a>)
and build options (see
<a href="#section:configuring:build_options">section <a href="#section:configuring:build_options">2.4.1</a></a>).</dd>
<dt><b><tt>show-depends</tt></b></dt>
<dd> Recursively display all the required dependencies
of a package. The results are splitted between system and <tt>robotpkg</tt>
dependencies, and missing dependencies are indicated.</dd>
<dt><b><tt>show-var</tt></b></dt>
<dd> Display the contents of a variable. This must be
invoked as <tt>make show-var VARNAME=foo</tt>, where <tt>foo</tt> is the name of
the variable to be displayed.</dd>
</dl>
<div class="p"><!----></div>
<h4>Package sets</h4>
<div class="p"><!----></div>
<dl>
<dt><b><tt>fetch-depends</tt>, <tt>replace-depends</tt>, <tt>update-depends</tt>, <tt>
clean-depends</tt></b></dt>
<dd>
This runs the same action as <tt>fetch</tt>, <tt>replace</tt>, <tt>update</tt> or
<tt>clean</tt> (respectively), but on all dependencies of the package,
including the package itself. Useful to update a meta-packages, for instance.</dd>
<dt><b><tt>fetch-<set></tt>, <tt>replace-<set></tt>, <tt>update-<set></tt>, <tt>
clean-<set></tt></b></dt>
<dd>
This runs the same action as <tt>fetch</tt>, <tt>replace</tt>, <tt>update</tt> or
<tt>clean</tt> (respectively), but on all members of the package set named <tt>
<set></tt>. See
<a href="#section:configuring:sets">section <a href="#section:configuring:sets">2.4.3</a></a>
for an explanation of package sets and how to configure them.</dd>
</dl>
<div class="p"><!----></div>
<a id="tth_sEc2.4"></a><h2>
2.4 Configuring robotpkg</h2> <a id="section:configuring">
</a>
<div class="p"><!----></div>
The whole <tt>robotpkg</tt> system is configured <em>via</em> a single, centralized file,
called <tt>robotpkg.conf</tt> and placed in the <tt>/opt/openrobots/etc</tt>
directory by default. This location might be redefined during the bootstrap
phase, see <a href="#section:bootstrapping">Section <a href="#section:bootstrapping">2.2</a></a>.
During the bootstrap, an initial configuration file is created with the
settings you provided to <tt>bootstrap</tt>.
<div class="p"><!----></div>
The format of the configuration file is that of the usual GNU style <tt>
Makefile</tt>s. The whole <tt>robotpkg</tt> configuration is done by setting variables in
this file. Note that you can define all kinds of variables, and no special
error checking (for example for spelling mistakes) takes place, so you have to
try it out to see if it works.
<div class="p"><!----></div>
<a id="tth_sEc2.4.1"></a><h3>
2.4.1 Selecting build options</h3> <a id="section:configuring:build_options">
</a>
<div class="p"><!----></div>
Some packages have build time options, usually to select between different
dependencies, enable optional support for big dependencies or enable
experimental features.
<div class="p"><!----></div>
To see which options, if any, a package supports, and which options are
mutually exclusive, run <tt>make show-options</tt>. For example:
<div class="p"><!----></div>
<pre>
Any of the following general options may be selected:
api Generate module API only
debug Produce debugging information for binary programs
* openprs Generate OpenPRS client code
* python Enable Python client code
*d tcl Generate TCL client code
* tclserv_client Generate C tclServ client code
xenomai Enable Xenomai support
</pre>
<div class="p"><!----></div>
This indicates that the package supports a number of options (<tt>api</tt>, <tt>
debug</tt>, <tt>openprs</tt> ...). The currently enabled options are indicated by a
star (<tt>*</tt>) and the default options are shown by the small letter <tt>d</tt> in
front of each option (here, only the <tt>tcl</tt> is enabled by default).
<div class="p"><!----></div>
The following variables can be defined in <tt>robotpkg.conf</tt> to select which
options to enable for a package:
<div class="p"><!----></div>
<dl>
<dt><b><tt>PKG_DEFAULT_OPTIONS</tt></b></dt>
<dd> can be used to select or disable
options for all packages that support them,</dd>
<dt><b><tt>PKG_OPTIONS.<pkgbase></tt></b></dt>
<dd> can be used to select or
disable options specifically for package <tt><pkgbase></tt>. Options listed
in these variables are selected, options prefixed by <tt>-</tt> are disabled
(e.g. <tt>-tcl</tt> would disable the <tt>tcl</tt> option).</dd>
</dl>
<div class="p"><!----></div>
A few examples:
<div class="p"><!----></div>
<pre>
PKG_DEFAULT_OPTIONS= debug
PKG_OPTIONS.genom= doc -tcl
</pre>
<div class="p"><!----></div>
It is important to note that options that were specifically suggested by the
package maintainer must be explicitely removed if you do not wish to include
the option. If you are unsure you can view the current state with <tt>make
show-options</tt>.
<div class="p"><!----></div>
The following settings are consulted in the order given, and the last setting
that selects or disables an option is used:
<div class="p"><!----></div>
<ol type="1">
<li> the default options as suggested by the package maintainer,
<div class="p"><!----></div>
</li>
<li> <tt>PKG_DEFAULT_OPTIONS</tt>,
<div class="p"><!----></div>
</li>
<li> <tt>PKG_OPTIONS.<pkgbase></tt>
<div class="p"><!----></div>
</li>
</ol>
<div class="p"><!----></div>
For groups of mutually exclusive options, the last option selected is used, all
others are automatically disabled. If an option of the group is explicitly
disabled, the previously selected option, if any, is used. It is an error if
no option from a required group of options is selected, and building the
package will fail.
<div class="p"><!----></div>
<a id="tth_sEc2.4.2"></a><h3>
2.4.2 Selecting build alternatives</h3> <a id="section:configuring:alternatives">
</a>
<div class="p"><!----></div>
Some packages have alternative dependencies, usually to select between
equivalent components or versions of components. This is similar to options but
the configuration is done globally for all packages that use the same
alternatives (this is to ensure consistency between packages).
<div class="p"><!----></div>
To see which alternatives, if any, a package uses, run <tt>make
show-options</tt>. For example:
<pre>
Available c-compiler alternatives (PREFER_ALTERNATIVE.c-compiler):
*1 gcc Use the GNU C compiler
2 clang Use the LLVM C compiler
ccache-gcc Use ccache and the GNU C compiler
ccache-clang Use ccache and the LLVM C compiler
</pre>
This indicates that the package supports a <tt>c-compiler</tt> alternative, for
which <tt>gcc</tt>, <tt>clang</tt>, <tt>ccache-gcc</tt> and <tt>ccache-clang</tt> can be
used. The currently selected alternative is shown by the star (<tt>*</tt>), and
the user preferences (or the default if the user has not set explicit
preferences) are indicated by the integer in front of the alternative item
(here <tt>gcc</tt> is the preferred alternative, then <tt>clang</tt> should be used
if <tt>gcc</tt> is not available. <tt>ccache</tt> should not be used).
<div class="p"><!----></div>
The following variables can be defined in <tt>robotpkg.conf</tt> to select which
alternative to use:
<div class="p"><!----></div>
<dl>
<dt><b><tt>PREFER_ALTERNATIVE.<alt></tt></b></dt>
<dd>
Alternatives are selected by setting the variable corresponding to the
alternative (<tt>PREFER_ALTERNATIVE.c-compiler</tt> in the example above) to a
space separated list, sorted by order of preference, containing one or
several of the items shown by <tt>make show-options</tt>.</dd>
</dl>
<div class="p"><!----></div>
<a id="tth_sEc2.4.3"></a><h3>
2.4.3 Defining collections of packages</h3> <a id="section:configuring:sets">
</a>
<div class="p"><!----></div>
Instead of installing, removing or updating packages one-by-one, you can define
collections of packages in your <tt>robotpkg.conf</tt>. Once one or more
collections are defined, they enable special targets that work on all the
packages of a collection.
<div class="p"><!----></div>
To define a collection, you have to give it a name and list the set of packages
forming the collection in the special <tt>PKGSET</tt> variable in <tt>
robotpkg.conf</tt>. The syntax is the following:
<div class="p"><!----></div>
<pre>
PKGSET.<name> = <list>
PKGSET_DESCR.<name> = short, optional description of the collection
</pre>
<div class="p"><!----></div>
where <tt><name></tt> is the name of the collection (any string is valid) and <tt>
<list></tt> is the list of packages in the collection, in the form <tt>
<category>/<name></tt>. For instance,
<div class="p"><!----></div>
<pre>
PKGSET.myset = architecture/genom middleware/pocolibs
PKGSET_DESCR.myset = an awesome duo
</pre>
<div class="p"><!----></div>
defines a collection named <tt>myset</tt> that contains the two packages <tt>
genom</tt> and <tt>pocolibs</tt> and describes itself with a rather doubtful sentence.
<div class="p"><!----></div>
For each collection <tt><name></tt> defined in <tt>robotpkg.conf</tt>, the following
targets are available: <tt>clean-<name></tt>, <tt>fetch-<name></tt>, <tt>
extract-<name></tt>, <tt>install-<name></tt>, <tt>replace-<name></tt>, <tt>
update-<name></tt> and <tt>deinstall-<name></tt>. They perform the same action as
their respective counterpart without <tt>-<name></tt> suffix, expect that they
work on all packages of the set. In addition, for the <tt>replace</tt>, <tt>
update</tt> and <tt>deinstall</tt> targets, they sort the packages in the order of
their dependencies so that the job is done a sensible order.
<div class="p"><!----></div>
For the user convenience, two special targets are provided. The
"<tt>installed</tt>" collection is always defined and represents all currently
installed packages. Invoking, for instance, the <tt>update-installed</tt> target
will therefore update all currently installed packages. The "<tt>depends</tt>"
collection is available only when the current working directory is inside a
package. It merely defines the current package and all of its dependencies as
the sole elements of the collection. Invoking, for instance, the <tt>
update-depends</tt> target will update all dependencies of the package in the
current directory.
<div class="p"><!----></div>
Two <tt>robotpkg.conf</tt> variables affect the default behaviour of <tt>
robotpkg</tt> regarding packages sets:
<div class="p"><!----></div>
<dl>
<dt><b>PKGSET_FAILSAFE</b></dt>
<dd> When working on a set, and this variable is set to
yes, robotpkg will continue with further packages instead of stopping on an
error. If set to 'no', stop on first error. Default: no.</dd>
<dt><b>PKGSET_STRICT</b></dt>
<dd> Specify if package sets should be considered as
'strict' or include dependencies of packages defined in the set. If set to
'yes', only package strictly defined in sets are considered. If set to 'no',
dependencies of packages listed in sets are added to their respective
sets. Default: no.</dd>
</dl>
<div class="p"><!----></div>
Each of these variables can be defined on a per-collection basis, by adding the
.<name> suffix to the variable name, where <name> is the name of the collection
to be configured.
<div class="p"><!----></div>
<a id="tth_sEc2.4.4"></a><h3>
2.4.4 Package specific configuration variables</h3>
<div class="p"><!----></div>
In this section, you can find variables that apply to one specific package.
Each variable is suffixed by <tt>.<pkg></tt>, where <tt><pkg></tt> is the actual
package name to which the variable should apply.
<div class="p"><!----></div>
<dl>
<dt><b>REPOSITORY.<pkg></b></dt>
<dd> locally overrides the default <tt>
MASTER_REPOSITORY</tt> defined for a package. This is useful if you want to
work with an alternative, perhaps local, repository when doing a <tt>make
checkout</tt>.</dd>
<dt><b>CHECKOUT_VCS_OPTS.<pkg></b></dt>
<dd> is a list of options used when fetching a
package via a <tt>make checkout</tt> command. The options are passed to the
"cvs checkout", "git clone" or "svn checkout" command that extract the
source archive.</dd>
</dl>
<div class="p"><!----></div>
<a id="tth_sEc2.4.5"></a><h3>
2.4.5 General configuration variables</h3>
<div class="p"><!----></div>
In this section, you can find some variables that apply to all <tt>robotpkg</tt>
packages.
<div class="p"><!----></div>
<div class="p"><!----></div>
<dl>
<dt><b>ACCEPTABLE_LICENSES</b></dt>
<dd> List of acceptable licenses. Whenever you try to
build a package whose license is not in this list, you will get an error
message that includes instructions on how to change this variable.</dd>
<dt><b>DISTDIR</b></dt>
<dd> Where to store the downloaded copies of the original source
distributions used for building <tt>robotpkg</tt> packages. The default is
<tt>$ROBOTPKG_DIR/distfiles</tt>.</dd>
<dt><b>PACKAGES</b></dt>
<dd> The top level directory for the binary packages. The default
is <tt>$ROBOTPKG_DIR/packages</tt>.</dd>
<dt><b>MASTER_SITE_BACKUP</b></dt>
<dd> List of backup locations for distribution files
if not found locally or in <tt>$MASTER_SITES</tt>. The default is<br />
<tt>http://softs.laas.fr/openrobots/robotpkg/distfiles/</tt>.</dd>
<dt><b>PKG_DEBUG_LEVEL</b></dt>
<dd> The level of debugging output which is displayed
whilst making and installing the package. The default value for this is 0,
which will not display the commands as they are executed (normal, default,
quiet operation); the value 1 will display all shell commands before their
invocation, and the value 2 will display both the shell commands before
their invocation, and their actual execution progress with <tt>set -x</tt>.</dd>
</dl>
<div class="p"><!----></div>
<a id="tth_sEc2.4.6"></a><h3>
2.4.6 Variables affecting the build process</h3>
<div class="p"><!----></div>
<dl>
<dt><b>WRKOBJDIR</b></dt>
<dd> The top level directory where, if defined, the separate
working directories will get created. This is useful for building packages
on a different filesystem than the <tt>robotpkg</tt> sources.</dd>
<dt><b>OBJHOSTNAME</b></dt>
<dd> If set to yes (the default), use hostname-specific
working directories, e.g. work.cactus, work.localhost. <tt>OBJHOSTNAME</tt>
takes precedence over <tt>OBJMACHINE</tt> (see below).</dd>
<dt><b>OBJMACHINE</b></dt>
<dd> If set to yes (the default) use machine-specific working
directories, e.g. work.Linux-i386.</dd>
<dt><b>DEPENDS_TARGET</b></dt>
<dd> By default, dependencies are only installed, and no
binary package is created for them. You can set this variable to <tt>
package</tt> to automatically create binary packages after installing
dependencies.</dd>
<dt><b>LOCALBASE</b></dt>
<dd> Where packages will be installed. The default value is <tt>
/opt/openrobots</tt>. Do not mix binary packages with different values
of <tt>LOCALBASE</tt>s!</dd>
<dt><b>MAKE_JOBS</b></dt>
<dd> When defined, specifies the maximum number of jobs that
are run in parallel when building packages with the default action. <tt>
MAKE_JOBS</tt> only affects the "build" target. <tt>MAKE_JOBS</tt> can be set to
any positive integer; useful values are around the number of processors on
the machine.
<div class="p"><!----></div>
<div class="p"><!----></div>
</dd>
</dl> <a id="tth_sEc2.4.7"></a><h3>
2.4.7 Additional flags to the compiler</h3>
<div class="p"><!----></div>
If you wish to set compiler variables such as <tt>CFLAGS</tt>, <tt>CXXFLAGS</tt>,
<tt>FFLAGS</tt> ... please make sure to use the <tt>+=</tt> operator instead of the
<tt>=</tt> operator:
<div class="p"><!----></div>
<pre>
CFLAGS+= -your -flags
</pre>
<div class="p"><!----></div>
Using <tt>CFLAGS=</tt> (i.e. without the "<tt>+</tt>") may lead to problems with
packages that need to add their own flags.
<div class="p"><!----></div>
If you want to pass flags to the linker, both in the configure step and the
build step, you can do this in two ways. Either set <tt>LDFLAGS</tt> or <tt>
LIBS</tt>. The difference between the two is that <tt>LIBS</tt> will be appended to
the command line, while <tt>LDFLAGS</tt> come earlier. <tt>LDFLAGS</tt> is pre-loaded
with rpath settings for machines that support it. As with <tt>CFLAGS</tt> you
should use the <tt>+=</tt> operator:
<div class="p"><!----></div>
<pre>
LDFLAGS+= -your -linkerflags
</pre>
<div class="p"><!----></div>
<a id="tth_sEc2.5"></a><h2>
2.5 Creating binary packages for everything</h2>
<div class="p"><!----></div>
There are two ways of getting a set of binary packages: manually building
the packages you need, or using <tt>robotpkg</tt> "bulk build" infrastructure.
<div class="p"><!----></div>
Bulk builds can also be used to test that packages compile and install cleanly,
and <tt>robotpkg</tt> provides reporting tools that can summarize the results of a
"bulk build".
<div class="p"><!----></div>
<a id="tth_sEc2.5.1"></a><h3>
2.5.1 Initial setup</h3> <a id="section:bulk:setup">
</a>
<div class="p"><!----></div>
The required setup for running bulk build merely consists in properly setting
up <tt>robotpkg</tt> itself. Details can be found in sections
<a href="#section:bootstrapping"><a href="#section:bootstrapping">2.2</a></a> and
<a href="#section:configuring"><a href="#section:configuring">2.4</a></a>.
<div class="p"><!----></div>
For instance, setup <tt>robotpkg</tt> in the <tt>/local/robotpkg</tt> directory:
<pre>
% mkdir -p /local/var/lib
% cd /local/var/lib
% git clone git://git.openrobots.org/git/robots/robotpkg
% cd robotpkg/bootstrap
% ./bootstrap --prefix=/local/robotpkg
</pre>
<div class="p"><!----></div>
You should install at least <tt>pkgtools/pkg_install</tt>, <tt>pkgtools/digest</tt>
and <tt>pkgtools/tnftp</tt>. Optionally, you can install <tt>pkgtools/rbulkit</tt>
that can generate pretty HTML reports
(<a href="#section:bulk:report">section <a href="#section:bulk:report">2.5.3</a></a>).
<pre>
% cd /local/var/lib/robotpkg
% cd pkgtools/rbulkit
% make update
</pre>
<div class="p"><!----></div>
You must configure the prefix directory where binary packages are built. This
is important: since binary package are not relocatable, this directory will be
the installation directory of all generated packages. However, if you use bulk
builds only as a way to test the build of your packages, any directory can be
configured. The following variables can be customized in <tt>robotpkg.conf</tt>:
<div class="p"><!----></div>
<dl>
<dt><b>BULKBASE?= /opt/openrobots</b></dt>
<dd>
The installation prefix of binary packages. This <b>must</b> be different
from the <tt>${LOCALBASE}</tt> directory where regular robotpkg packages are
installed. The default is <tt>/opt/openrobots</tt>.
<div class="p"><!----></div>
</dd>
<dt><b>BULK_LOGDIR?= ${LOCALBASE}/var/log/bulk</b></dt>
<dd>
The directory where log files are kept. The default is to put log files in
the regular installation prefix of robotpkg (<tt>
/local/robotpkg/var/log/bulk</tt> in the example setup above).
<div class="p"><!----></div>
</dd>
<dt><b>BULK_TAG</b></dt>
<dd>
A name (alphanumeric characters) for that bulk session. The default name is
based on the machine operating system and version. Giving a different name
can be used to distinguish between different runs, but in this case it is
probably easier to pass that variable definition on the command line.</dd>
</dl>
<div class="p"><!----></div>
Finally, you must define at least one package set (see
<a href="#section:configuring:sets">section <a href="#section:configuring:sets">2.4.3</a></a>)
containing the list of packages to build (running bulk build on a single
package is also supported, but has only limited interest). For instance, create
a "<tt>huge</tt>" and a "<tt>tiny</tt>" set by placing the following definitions
in your <tt>robotpkg.conf</tt> file:
<pre>
PKGSET_DESCR.huge= Huge bulk set: everything!
PKGSET.huge= */*:*
PKGSET_DESCR.tiny= Tiny bulk set: just one package + dependencies
PKGSET.tiny= shell/eltclsh
PKGSET_STRICT.tiny= no
</pre>
<div class="p"><!----></div>
<a id="tth_sEc2.5.2"></a><h3>
2.5.2 Running bulk builds</h3> <a id="section:bulk:run">
</a>
<div class="p"><!----></div>
The target for running bulk builds is called <tt>bulk</tt>. You can run a bulk
build for one package by just running <tt>make bulk</tt> in the package
directory. Running <tt>make bulk-depends</tt> would run the bulk target on the
package and all of its dependencies. More useful though is to use some
predefined sets of packages as explained in the previous section:
<pre>
% cd /local/var/lib/robotpkg
% make bulk-tiny
</pre>
This would run the <tt>bulk</tt> target on each package of the <tt>tiny</tt> set (see
<a href="#section:configuring:sets">section <a href="#section:configuring:sets">2.4.3</a></a> for an
explanation of the -<set> targets).
<div class="p"><!----></div>
This should run for a while and enventually populate <tt>${BULK_LOGDIR}</tt>
with lots of log files. You can then examine them manually, or generate some
reports with <tt>rbulkit</tt>.
<div class="p"><!----></div>
<a id="tth_sEc2.5.3"></a><h3>
2.5.3 Generating pretty reports</h3> <a id="section:bulk:report">
</a>
<div class="p"><!----></div>
If you installed the <tt>pkgtools/rbulkit</tt> package, you can use the <tt>
rbulk-report</tt> program (installed in <tt><prefix>/sbin</tt>) to generate:
<ul>
<li> an <tt>sqlite</tt> database containing the bulk results
<div class="p"><!----></div>
</li>
<li> an HTML report
<div class="p"><!----></div>
</li>
</ul>
<div class="p"><!----></div>
With the sample setup used throughout this chapter, the <tt>sqlite</tt> database
can be populated like so:
<pre>
% rbulk-report log2db /local/robotpkg/var/log/bulk sqlite.db
</pre>
Note that the command will <em>append</em> the results to a pre-existing <tt>
sqlite.db</tt>. Only results using the same <tt>BULK_TAG</tt> will be overwritten.
<div class="p"><!----></div>
The HTML report can then be updated like so:
<pre>
% rbulk-report db2html sqlite.db /tmp/bulk-report/
</pre>
The report can then be viewed by pointing a web browser to <tt>
/tmp/bulk-report/index.html</tt>.
<div class="p"><!----></div>
To go further, please read the <tt>rbulk-report(1)</tt> manual for available
commands and options.
<div class="p"><!----></div>
<a id="tth_sEc2.5.4"></a><h3>
2.5.4 Automated bulk builds</h3> <a id="section:bulk:auto">
</a>
<div class="p"><!----></div>
The <tt>pkgtools/rbulkit</tt> package contains sample scripts and programs that
can be used to automate bulk builds. First, there is the <tt>rbulk-build</tt>
script, that does essentially all the steps described in the previous sections.
See <tt>rbulk-build(1)</tt> for more information. It relies on a properly setup
<tt>robotpkg</tt> and <tt>robotpkg.conf</tt>.
<div class="p"><!----></div>
There are also the <tt>rbulk-watchd</tt> and <tt>rbulk-notify</tt> programs, than can
respectively wait for and signal notifications over TCP. This can be used to
trigger a bulk build in a commit hook, for instance. See <tt>rbulk-watchd(1)</tt>
and <tt>rbulk-notify(1)</tt>.
<div class="p"><!----></div>
Finally, <tt>rbulk-dispatch</tt> and <tt>rbulk-dispatchd</tt> are able to parallelize
jobs on a group of machines according to user defined priorities. See
<tt>rbulk-dispatchd(1)</tt>.
<div class="p"><!----></div>
<a id="tth_chAp3"></a><h1>
3 <br />The robotpkg developer's guide</h1>
<a id="chapter:developer">
</a>
<div class="p"><!----></div>
This part of the documentation deals with creating and modifying packages.
<div class="p"><!----></div>
<a id="tth_sEc3.1"></a><h2>
3.1 Package files, directories and contents</h2> <a id="section:pkgvars">
</a>
<div class="p"><!----></div>
Whenever you're preparing a package, there are a number of files involved which
are described in the following sections.
<div class="p"><!----></div>
<a id="tth_sEc3.1.1"></a><h3>
3.1.1 Makefile</h3> <a id="subsection:makefile">
</a>
<div class="p"><!----></div>
Building, installation and creation of a package are all controlled by the
package's Makefile. The Makefile describes various things about a package,
for example from where to get it, how to configure, build, and install it.
<div class="p"><!----></div>
A package Makefile contains several sections that describe the package.
<div class="p"><!----></div>
In the first section there are the following variables, which should appear
exactly in the order given here. The order and grouping of the variables is
mostly historical and has no further meaning.
<div class="p"><!----></div>
<dl>
<dt><b>PKGREVISION</b></dt>
<dd> Defines the <tt>robotpkg</tt> revision number of the package. This
<em>should not be set</em> for a new package. See
<a href="#section:genvars:PKGREVISION">Section <a href="#section:genvars:PKGREVISION">3.2.4</a></a>
for details.
<div class="p"><!----></div>
</dd>
<dt><b>MASTER_SITES</b></dt>
<dd> In simple cases, <tt>MASTER_SITES</tt> defines all URLs
from where the distfile, whose name is derived from the <tt>DISTNAME</tt>
variable, is fetched.
<div class="p"><!----></div>
When actually fetching the distfiles, each item from <tt>MASTER_SITES</tt>
gets the name of each distfile appended to it, without an intermediate
slash. Therefore, all site values have to end with a slash or other
separator character. This allows for example to set <tt>MASTER_SITES</tt> to a
URL of a CGI script that gets the name of the distfile as a parameter. In
this case, the definition would look like:
<blockquote><div>
<tt>MASTER_SITES= http://www.example.com/download.cgi?file=</tt>
</div></blockquote>
<div class="p"><!----></div>
There are some predefined values for <tt>MASTER_SITES</tt>, which can be used
in packages. The names of the variables should speak for themselves.
<blockquote><div><tt>
${MASTER_SITE_SOURCEFORGE}<br />
${MASTER_SITE_GNU}<br />
${MASTER_SITE_OPENROBOTS}
</tt></div></blockquote>
<div class="p"><!----></div>
If you choose one of these predefined sites, you may want to specify a
subdirectory of that site. Since these macros may expand to more than one
actual site, <em>you must</em> use the following construct to specify a
subdirectory:
<blockquote><div><tt>
MASTER_SITES= ${MASTER_SITE_SOURCEFORGE:=project_name/}
</tt></div></blockquote>
Note the trailing slash after the subdirectory name.
<div class="p"><!----></div>
</dd>
<dt><b>FETCH_METHOD</b></dt>
<dd> This is the method used to download the distfile from
<tt>MASTER_SITES</tt>. It defaults to '<tt>archive</tt>' which corresponds to the
normal situation where distfile is an archive available from <tt>
MASTER_SITES</tt>, so it normally needs not to be set.
<div class="p"><!----></div>
However, it can happen that a software provider does not provide any archive
available for download but has only a public repository. In this case, <tt>
FETCH_METHOD</tt> can be set to <tt>cvs</tt>, <tt>git</tt> or <tt>svn</tt> according to
the kind of repository available. <tt>MASTER_SITES</tt> is then interpreted as
a repository of the form <tt>url[@revision[+module]]</tt>, where the bits
between square brackets are optional and refer to a particular revision and
module in the repository located at <tt>url</tt>. <tt>url</tt> can take any form
supported by the underlying fetch tool (<tt>cvs</tt>, <tt>git</tt> or <tt>
svn</tt>). It is <em>strongly</em> advised to define at least a specific revision
to be checked out, so that the package can be reproducibly installed in a
known state.
<div class="p"><!----></div>
</dd>
<dt><b>MASTER_REPOSITORY</b></dt>
<dd> defines a VCS repository from where a "<tt>make
checkout</tt>" will download the latest revision of a software. <tt>
MASTER_REPOSITORY</tt> is a list of 2 or 3 elements. The first element is the
VCS tool to be used: it must be one of <tt>cvs</tt>, <tt>git</tt> or <tt>svn</tt>.
The second element is the location of the repository. It must be written in
a syntax understood by the actual VCS tool. The third optional element is a
list of specific elements to be checked out instead of the default (the
whole repository).
<div class="p"><!----></div>
</dd>
<dt><b>CHECKOUT_VCS_OPTS</b></dt>
<dd> is a list of options used when fetching a
package via a <tt>make checkout</tt> command. The options are passed to the
"cvs checkout", "git clone" or "svn checkout" command that extract the
source archive.</dd>
</dl>
<div class="p"><!----></div>
The second section contains information about separately downloaded patches, if any.
<div class="p"><!----></div>
<dl>
<dt><b>PATCHFILES</b></dt>
<dd> Name(s) of additional files that contain distribution
patches distributed by the author or other maintainers. There is no
default. robotpkg will look for them at <tt>PATCH_SITES</tt>. They will
automatically be uncompressed before patching if the names end with .gz
or .Z.
<div class="p"><!----></div>
</dd>
<dt><b>PATCH_SITES</b></dt>
<dd> Primary location(s) for distribution patch files (see
<tt>PATCHFILES</tt> above) if not found locally.</dd>
</dl>
<div class="p"><!----></div>
The third section contains the following variables.
<div class="p"><!----></div>
<dl>
<dt><b>MAINTAINER</b></dt>
<dd> is the email address of the person who feels responsible
for this package, and who is most likely to look at problems or questions
regarding this package. Other developers may contact the <tt>MAINTAINER</tt>
before making changes to the package, but are not required to do so. When
packaging a new program, set <tt>MAINTAINER</tt> to yourself. If you really
can't maintain the package for future updates, set it to
<tt><tt><</tt>[email protected]<tt>></tt></tt>.
<div class="p"><!----></div>
</dd>
<dt><b>HOMEPAGE</b></dt>
<dd> is a URL where users can find more information about the
package.
<div class="p"><!----></div>
</dd>
<dt><b>COMMENT</b></dt>
<dd> is a one-line description of the package (should not include
the package name).
<div class="p"><!----></div>
</dd>
<dt><b>LICENSE</b></dt>
<dd> Denoting that a package may be installed and used according
to a particular license is done by placing the license in <tt>
robotpkg/licenses</tt> and setting the LICENSE variable to a string identifying
the license file, e.g. in <tt>shell/eltclsh</tt>:
<blockquote><div>
LICENSE= 2-clause-bsd
</div></blockquote>
<div class="p"><!----></div>
The license tag mechanism is intended to address copyright-related issues
surrounding building, installing and using a package, and not to address
redistribution issues (see RESTRICTED and NO_PUBLIC_SRC, etc.). Packages
with redistribution restrictions should set these tags.</dd>
</dl>
<div class="p"><!----></div>
Other variables affecting the build process may be gathered in their own
section.
<div class="p"><!----></div>
<dl>
<dt><b>PKG_SUPPORTED_OPTIONS</b></dt>
<dd> is the list of build options supported by the
package. A number of related variables are used in combination with <tt>
PKG_SUPPORTED_OPTIONS</tt>. See <a href="#section:genvars:PKG_SUPPORTED_OPTIONS">Section <a href="#section:genvars:PKG_SUPPORTED_OPTIONS">3.2.1</a></a> for details.</dd>
</dl>
<div class="p"><!----></div>
<a id="tth_sEc3.1.2"></a><h3>
3.1.2 distinfo</h3> <a id="subsection:distinfo">
</a>
<div class="p"><!----></div>
The distinfo file contains the message digest, or checksum, of each distfile
needed for the package. This ensures that the distfiles retrieved from the
Internet have not been corrupted during transfer or altered by a malign force
to introduce a security hole. Due to recent rumor about weaknesses of digest
algorithms, all distfiles are protected using both SHA1 and RMD160 message
digests, as well as the file size.
<div class="p"><!----></div>
The distinfo file also contains the checksums for all the patches found in the
patches directory (see
<a href="#subsection:patches">Section <a href="#subsection:patches">3.1.4</a></a>).
<div class="p"><!----></div>
To regenerate the distinfo file, use the <tt>make distinfo</tt> or <tt>make mdi</tt>
command.
<div class="p"><!----></div>
<a id="tth_sEc3.1.3"></a><h3>
3.1.3 PLIST</h3>
<a id="subsection:PLIST">
</a>
<div class="p"><!----></div>
This file governs the files that are installed on your system: all the
binaries, manual pages, etc. There are other directives which may be entered in
this file, to control the creation and deletion of directories, and the
location of inserted files.
<div class="p"><!----></div>
The names used in the PLIST are relative to the installation prefix (<tt>
${PREFIX}</tt>), which means that it cannot register files outside this
directory (absolute path names are not allowed). As a general sanity rule,
robotpkg must not alter any files outside <tt>${PREFIX}</tt> anyway and, in
particular, not modify automatically existing configuration files. If a package
needs to install files outside <tt>${PREFIX}</tt>, the best option is to
install them with robotpkg inside <tt>${PREFIX}</tt> (e.g. <tt>
${PREFIX}/etc</tt> or <tt>${PREFIX}/var</tt>) and create a <tt>MESSAGE</tt> file
that will instruct the user to manually link or copy the files in question to
their final location. See the package <tt>hardware/ieee1394-kmod</tt> for an
example of such package.
<div class="p"><!----></div>
In order to create or update a <tt>PLIST</tt>, you can use the <tt>make
print-PLIST</tt> command to output a PLIST that matches any new installed files
since the package was extracted. This command will generate a <tt>
PLIST.guess</tt> file which you must move manually to <tt>PLIST</tt> after reviewing
the result of the semi-automatic generation. In order to fine tune the <tt>
PLIST</tt> or its semi-automatic generation, specific variables documented in
<a href="#section:genvars:PLIST">section <a href="#section:genvars:PLIST">3.2.2</a></a> and
<a href="#section:genvars:print-PLIST">section <a href="#section:genvars:print-PLIST">3.2.3</a></a>
may be used.
<div class="p"><!----></div>
<a id="tth_sEc3.1.4"></a><h3>
3.1.4 patches/*</h3> <a id="subsection:patches">
</a>
<div class="p"><!----></div>
Some packages may not work out-of-the box with robotpkg. Therefore, a number of
custom patch files may be needed to make the package work. These patch files
are found in the <tt>patches/</tt> directory. If you want to share patches between
multiple packages in robotpkg, e.g. because they use the same distfiles, set
<tt>PATCHDIR</tt> to the path where the patch files can be found, e.g.:
<blockquote><div>
PATCHDIR= ../../devel/boost/patches
</div></blockquote>
<div class="p"><!----></div>
The file names of the patch files must be of the form <tt>patch-*</tt>, and they
are usually named <tt>patch-[a-z][a-z]</tt>. In the <em>patch</em> phase, these
patches are automatically applied to the files in <tt>${WRKSRC}</tt>
directory after extracting them, in alphabetic order.
<div class="p"><!----></div>
The <tt>patch-*</tt> files should be in <tt>diff -bu</tt> format, and apply without a
fuzz to avoid problems. (To force patches to apply with fuzz you can set <tt>
PATCH_FUZZ_FACTOR=-F2</tt> in a package's <tt>Makefile</tt>).
<div class="p"><!----></div>
Each patch file should be commented so that any developer who knows the code of
the application can make some use of the patch. Special care should be taken
for the upstream developers, since we generally want that they accept robotpkg
patches, so there is less work in the future. When adding a patch that corrects
a problem in the distfile (rather than e.g. enforcing robotpkg's view of where
man pages should go), send the patch as a bug report to the maintainer. This
benefits non-robotpkg users of the package, and usually makes it possible to
remove the patch in future version.
<div class="p"><!----></div>
When you add or modify existing patch files, remember to generate the checksums
for the patch files by using the <tt>make mdi</tt> command, see
<a href="#subsection:distinfo">Section <a href="#subsection:distinfo">3.1.2</a></a>.
<div class="p"><!----></div>
<a id="tth_sEc3.2"></a><h2>
3.2 General operation</h2> <a id="section:genvars">
</a>
<div class="p"><!----></div>
<a id="tth_sEc3.2.1"></a><h3>
3.2.1 Adding build options to a package</h3> <a id="section:genvars:PKG_SUPPORTED_OPTIONS">
</a>
<div class="p"><!----></div>
Build options (see <a href="#section:configuring:build_options">section <a href="#section:configuring:build_options">2.4.1</a></a> for details) can be defined
in a package by properly configuring the following variables.
<div class="p"><!----></div>
<dl>
<dt><b>PKG_SUPPORTED_OPTIONS</b></dt>
<dd>
This is a list of build options supported by the package. This variable
should be set in a package Makefile. E.g.,
<pre>
PKG_SUPPORTED_OPTIONS= ipv6 ssl
</pre>
If this variable is not defined, <tt>PKG_OPTIONS</tt> is set to the empty list
and the package is otherwise treated as not using the options framework.
<div class="p"><!----></div>
</dd>
<dt><b>PKG_OPTION_DESCR.<opt></b></dt>
<dd>
This is the textual description of the option <opt> which is displayed by
the <tt>make show-options</tt> target. E.g.,
<pre>
PKG_OPTION_DESCR.bar= Enable the bar option.
</pre>
<div class="p"><!----></div>
</dd>
<dt><b>PKG_OPTION_SET.<opt> (resp. PKG_OPTION_UNSET.<opt>)</b></dt>
<dd>
This is a makefile fragment that is evaluated when the option <opt> is set
(resp unset) for the package. E.g.,
<pre>
PKG_OPTION_SET.bar= CFLAGS+=-DBAR
PKG_OPTION_UNSET.bar= CFLAGS+=-DNO_BAR
</pre>
Complex (multiline) <tt>_SET</tt> or <tt>_UNSET</tt> actions can be defined with
the <tt>define</tt> command of GNU-make. It is for instance possible to add
additional dependencies: see the example below.
<div class="p"><!----></div>
</dd>
<dt><b>PKG_OPTIONS_OPTIONAL_GROUPS</b></dt>
<dd>
This is a list of names of groups of mutually exclusive options. The
options in each group are listed in <tt>PKG_OPTIONS_GROUP.<groupname></tt>.
The most specific setting of any option from the group takes precedence over
all other options in the group. Options from the groups will be
automatically added to <tt>PKG_SUPPORTED_OPTIONS</tt>.
<div class="p"><!----></div>
</dd>
<dt><b>PKG_OPTIONS_REQUIRED_GROUPS</b></dt>
<dd>
Like <tt>PKG_OPTIONS_OPTIONAL_GROUPS</tt>, but building the packages will
fail if no option from the group is selected.
<div class="p"><!----></div>
</dd>
<dt><b>PKG_OPTIONS_NONEMPTY_SETS</b></dt>
<dd>
This is a list of names of sets of options. At least one option from each
set must be selected. The options in each set are listed in <tt>
PKG_OPTIONS_SET.<setname></tt>. Options from the sets will be automatically
added to <tt>PKG_SUPPORTED_OPTIONS</tt>.
<div class="p"><!----></div>
</dd>
<dt><b>PKG_OPTIONS_SUFFIX</b></dt>
<dd>
The suffix in <tt>PKG_OPTIONS.suffix</tt> variable the user can set to enable
or disable options specifically for this package. Defaults to <tt>
${PKGBASE}</tt>.
<div class="p"><!----></div>
</dd>
<dt><b>PKG_SUGGESTED_OPTIONS</b></dt>
<dd>
This is a list of build options which are enabled by default. This defaults
to the empty list.</dd>
</dl>
<div class="p"><!----></div>
Here is an example Makefile fragment for a 'wibble' package. This fragment
should be included in the 'wibble' package Makefile.
<div class="p"><!----></div>
<pre>
PKG_OPTIONS_SUFFIX= wibble # this is the default
PKG_SUPPORTED_OPTIONS= foo bar
PKG_OPTIONS_OPTIONAL_GROUPS= robot
PKG_OPTIONS_GROUP.robot= lama hrp2
PKG_SUGGESTED_OPTIONS= foo
PKG_OPTION_DESCR.foo= Enable the foo option.
PKG_OPTION_DESCR.bar= Build with the bar package.
PKG_OPTION_DESCR.lama= Build for the lama robot.
PKG_OPTION_DESCR.hrp2= Build for the hrp2 robot.
define PKG_OPTION_SET.bar
CFLAGS+=-DNO_BAR
include ../../pkg/bar/depend.mk
endef
PKG_OPTION_UNSET.bar= CFLAGS+=-DNO_BAR
</pre>
<div class="p"><!----></div>
<a id="tth_sEc3.2.2"></a><h3>
3.2.2 Customizing the PLIST</h3> <a id="section:genvars:PLIST">
</a>
<div class="p"><!----></div>
The packing list of a package is usually computed from the <tt>PLIST</tt> file
located in the package directory. The following variables determine how the
final packing list is setup:
<div class="p"><!----></div>
<dl>
<dt><b>PLIST_SRC</b></dt>
<dd>
The source file(s) for the final packing list. By default, its value
is constructed from the PLIST.* files within the package directory:
<pre>
PLIST_SRC+= ${PKGDIR}/PLIST.${OS_KERNEL}
PLIST_SRC+= ${PKGDIR}/PLIST.${OPSYS}
PLIST_SRC+= ${PKGDIR}/PLIST.${MACHINE_ARCH}
PLIST_SRC+= ${PKGDIR}/PLIST.${OPSYS}-${MACHINE_ARCH}
PLIST_SRC+= ${PKGDIR}/PLIST
</pre>
If a Makefile sets <tt>PLIST_SRC</tt>, the defaults are not used.
<div class="p"><!----></div>
</dd>
<dt><b>DYNAMIC_PLIST_DIRS</b></dt>
<dd>
A list of directories, absolute or relative to the installation
<tt>${PREFIX}</tt>, whose contents are dynamically added to the final packing
list. This is useful to handle non-deterministic packing lists, most notably
those generated by <tt>doxygen</tt>. This should be used with care, since <tt>
DYNAMIC_PLIST_DIRS</tt> somewhat defeats the purpose of the packing list.
<div class="p"><!----></div>
</dd>
<dt><b>PLIST_SUBST</b></dt>
<dd>
The <tt>PLIST</tt> file(s) of a package may also contain variable references
(in the <tt>${VAR}</tt> form) that are expanded at intallation time. The
following variables are supported by default:
<pre>
PKGBASE
PKGNAME
PKGVERSION
OPSYS
OS_VERSION
OS_KERNEL
OS_KERNEL_VERSION
PKGMANDIR
PKGINFODIR
PLIST.<opt> # for all supported options
PLIST.no<opt>
</pre>
<tt>PLIST.<opt></tt> is special: one such variable is defined for each
supported build option of the package. It can be used to dynamically enable
an entry of the packing list, depending on the build options configuration.
A <tt>${PLIST.<opt>}</tt> variable may only be present only at the beginning
of a line. Technically, <tt>${PLIST.<opt>}</tt> expands to a packing list
comment <tt>@comment</tt> when the option <tt><opt></tt> is not enabled, and to
the empty string otherwise.
<div class="p"><!----></div>
<tt>PLIST.no<opt></tt> is similar to <tt>PLIST.<opt></tt>, but it enables a <tt>
PLIST</tt> entry only if the corresponding option is not enabled.
<div class="p"><!----></div>
Other substitutions may be added by adding definitions to the <tt>
PLIST_SUBST</tt> variable. For instance, a package may define the <tt>FOO</tt>
variable substitution like so:
<pre>
PLIST_SUBST+= FOO=${FOO}
</pre>
This would instruct the packing list generator to replace all occurences of
<tt>${FOO}</tt> by the value of the <tt>${FOO}</tt> variable in the Makefile.
<div class="p"><!----></div>
</dd>
<dt><b>GENERATE_PLIST</b></dt>
<dd>
A sequence of commands, terminating in a semicolon, that outputs contents
for a PLIST to stdout and is appended to the contents of
<tt>${PLIST_SRC}</tt>. The default works for almost all packages, and it is
usually not needed to define a custom command.
<div class="p"><!----></div>
</dd>
<dt><b>PLIST_FILTER</b></dt>
<dd>
A sequence of commands, each starting with a pipe, that filter out the
packing list. This is to be used only in rare situations, and a standard
package should not need to customize this.</dd>
</dl>
<div class="p"><!----></div>
<a id="tth_sEc3.2.3"></a><h3>
3.2.3 Customizing the semi-automatic PLIST generation</h3> <a id="section:genvars:print-PLIST">
</a>
<div class="p"><!----></div>
The semi-automatic initial PLIST generation does not handle package options.
If the list of installed files depends on the package build options,
<tt>${PLIST.<opt>}</tt> variable references, detailed in
<a href="#section:genvars:PLIST">section <a href="#section:genvars:PLIST">3.2.2</a></a>, must be
manually added to the result of <tt>make print-PLIST</tt>.
<div class="p"><!----></div>
<a id="tth_sEc3.2.4"></a><h3>
3.2.4 Incrementing versions when fixing an existing package</h3> <a id="section:genvars:PKGREVISION">
</a>
<div class="p"><!----></div>
When making fixes to an existing package it can be useful to change the version
number in <tt>PKGNAME</tt>. To avoid conflicting with future versions by the
original author, a "r1", "r2", ... suffix can be used on package versions by
setting <tt>PKGREVISION=1</tt> (<tt>2</tt>, ...) in the package Makefile. E.g.
<blockquote><div>
DISTNAME= foo-17.42<br />
PKGREVISION= 9
</div></blockquote>
will result in a <tt>PKGNAME</tt> of "foo-17.42r9". The "r" is treated like a "."
by the package tools.
<div class="p"><!----></div>
<tt>PKGREVISION</tt> should be incremented for any non-trivial change in the
resulting binary package. Without a <tt>PKGREVISION</tt> bump, someone with the
previous version installed has no way of knowing that their package is out
of date. Thus, changes without increasing <tt>PKGREVISION</tt> are essentially
labeled "this is so trivial that no reasonable person would want to
upgrade", and this is the rough test for when increasing <tt>PKGREVISION</tt>
is appropriate. Examples of changes that do not merit increasing <tt>
PKGREVISION</tt> are:
<ul>
<li> Changing <tt>HOMEPAGE</tt>, <tt>MAINTAINER</tt> or comments in Makefile.
<div class="p"><!----></div>
</li>
<li> Changing build variables if the resulting binary package is the same.
<div class="p"><!----></div>
</li>
<li> Changing <tt>DESCR</tt>.
<div class="p"><!----></div>
</li>
<li> Adding <tt>PKG_OPTIONS</tt> if the default options don't change.
<div class="p"><!----></div>
</li>
</ul>
<div class="p"><!----></div>
Examples of changes that do merit an increase to <tt>PKGREVISION</tt> include:
<ul>
<li> Security fixes
<div class="p"><!----></div>
</li>
<li> Changes or additions to a patch file
<div class="p"><!----></div>
</li>
<li> Changes to the <tt>PLIST</tt>
<div class="p"><!----></div>
</li>
<li> A dependency is changed or renamed.
<div class="p"><!----></div>
</li>
</ul>
<div class="p"><!----></div>
<tt>PKGREVISION</tt> must also be incremented when dependencies have ABI changes.
<div class="p"><!----></div>
When a new release of the package is released, the <tt>PKGREVISION</tt> must be
removed.
<div class="p"><!----></div>
<a id="tth_sEc3.2.5"></a><h3>
3.2.5 Substituting variable text in the package files</h3> <a id="section:genvars:SUBST">
</a>
<div class="p"><!----></div>
When you want to replace the same text in multiple files or when the
replacement text varies, patches alone cannot help. This is where the SUBST
framework comes in. It provides an easy-to-use interface for replacing text in
files. Example:
<pre>
SUBST_CLASSES+= fix-paths
SUBST_STAGE.fix-paths= pre-configure
SUBST_MESSAGE.fix-paths= Fixing absolute paths.
SUBST_FILES.fix-paths= src/*.c
SUBST_SED.fix-paths= -e 's,"/usr/local,"${PREFIX},g'
</pre>
<div class="p"><!----></div>
<tt>SUBST_CLASSES</tt> is a list of identifiers that are used to identify the
different <tt>SUBST</tt> blocks that are defined. The <tt>SUBST</tt> framework is
used by <tt>robotpkg</tt> , so it is important to always use the <tt>+=</tt> operator
with this variable. Otherwise some substitutions may be skipped.
<div class="p"><!----></div>
The remaining variables of each <tt>SUBST</tt> block are parameterized with the
identifier from the first line (<tt>fix-paths</tt> in this case).
<div class="p"><!----></div>
<tt>SUBST_STAGE.*</tt> specifies the stage at which the replacement will take
place. All combinations of pre-, do- and post- together with a phase name are
possible, though only few are actually used. Most commonly used are post-patch
and pre-configure. Of these two, pre-configure should be preferred because then
it is possible to run <tt>make patch</tt> and have the state after applying the
patches but before making any other changes. This is especially useful when you
are debugging a package in order to create new patches for it. Similarly,
post-build is preferred over pre-install, because the install phase should
generally be kept as simple as possible. When you use post-build, you have the
same files in the working directory that will be installed later, so you can
check if the substitution has succeeded.
<div class="p"><!----></div>
<tt>SUBST_MESSAGE.*</tt> is an optional text that is printed just before the
substitution is done.
<div class="p"><!----></div>
<tt>SUBST_FILES.*</tt> is the list of shell globbing patterns that specifies the
files in which the substitution will take place. The patterns are interpreted
relatively to the <tt>WRKSRC</tt> directory.
<div class="p"><!----></div>
<tt>SUBST_SED.*</tt> is a list of arguments to <tt>sed(1)</tt> that specify the
actual substitution. Every sed command should be prefixed with -e, so that all
<tt>SUBST</tt> blocks look uniform.
<div class="p"><!----></div>
There are some more variables, but they are so seldomly used that they are only
documented in the mk/internal/subst.mk file.
<div class="p"><!----></div>
<a id="tth_sEc3.3"></a><h2>
3.3 The build phase</h2> <a id="section:buildvars">
</a>
<div class="p"><!----></div>
For building a package, a rough equivalent of the following code is executed.
<pre>
for d in ${BUILD_DIRS}; do \
cd ${WRKSRC} \
&& cd ${d} \
&& env ${MAKE_ENV} \
${MAKE_PROGRAM} ${BUILD_MAKE_FLAGS} \
-f ${MAKE_FILE} \
${BUILD_TARGET}
done
</pre>
<div class="p"><!----></div>
The following variables affecting the build process of a package may be defined
in a package <tt>Makefile</tt>:
<div class="p"><!----></div>
<dl>
<dt><b>NO_BUILD</b></dt>
<dd> (default: unset). If there is no build step at all, set
<tt>NO_BUILD</tt> to "yes".
<div class="p"><!----></div>
</dd>
<dt><b>MAKE_PROGRAM</b></dt>
<dd> (default: <tt>MAKE</tt>) is the program used to perform
the actual build in a package.
<div class="p"><!----></div>
</dd>
<dt><b>BUILD_DIRS</b></dt>
<dd> (default: ".") is a list of pathnames relative to <tt>
WRKSRC</tt>. In each of these directories, <tt>MAKE_PROGRAM</tt> is run with the
environment <tt>MAKE_ENV</tt> and arguments <tt>BUILD_MAKE_FLAGS</tt>.
<div class="p"><!----></div>
</dd>
<dt><b>BUILD_TARGET</b></dt>
<dd> (default: "all") is the default <tt>make</tt> target for
building the package.
<div class="p"><!----></div>
</dd>
<dt><b>MAKE_JOBS_SAFE</b></dt>
<dd> Whether the package supports parallel builds. If set
to yes, at most <tt>MAKE_JOBS</tt> jobs are carried out in parallel. The
default value is "yes", and packages that don't support it must explicitly
set it to "no".</dd>
</dl>
<div class="p"><!----></div>
<div class="p"><!----></div>
</div></div>
</body>
</html>
此处可能存在不合适展示的内容，页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容，可点击提交进行申诉，我们将尽快为您处理。
马建仓 AI 助手