autoproj 1.3.4 → 1.4.0

data/doc/guide/src/default.css

@@ -35,6 +35,13 @@ a:hover {
 text-decoration:underline;
 }
 
+img.full {
+margin-left: auto;
+margin-right: auto;
+margin-top: 2em;
+margin-bottom: 2em;
+}
+
 a img{
 border:0;
 }
@@ -253,6 +260,10 @@ padding:20px;
 background:#eee;
 color:#222;
 border:2px solid #ddd;
+margin-top: 3em;
+margin-bottom: 3em;
+margin-left: 2em;
+margin-right: 2em;
 }
 
 .warning{

data/doc/guide/src/default.template

@@ -60,7 +60,7 @@
       <div id="sidebar">
 
         <h2 class="sidelink menuheader"><a id="sitemenu"></a>Main Menu</h2>
-        <div id="menu">{menu: {max_levels: 2, show_current_subtree_only: true, nested: true, used_nodes: files}}</div>
+        <div id="menu">{menu: {min_levels: 2, max_levels: 2, show_current_subtree_only: false, nested: true, used_nodes: files}}</div>
         <br>
         <a class="hide" href="#top" accesskey="1">Top of page</a>
 

data/doc/guide/src/error_messages.page

@@ -10,7 +10,8 @@ definition exists in one of the osdeps files.
 
 _Long explanation_: XXXX is listed as an operating system dependency by one of
 the packages that you requested to build. Two solutions: (i) the package should
-*not* depend on it, and you should modify the package's manifest.xml file. (ii)
+*not* depend on it, and you should modify the [package's
+manifest.xml](package_sets/manifest-xml.html) file. (ii)
 the package should depend on it and you should list the OS package in [the
 relevant osdeps file](osdeps.html)
 

data/doc/guide/src/htmldoc.metainfo

@@ -2,3 +2,7 @@
     title: Introduction
     sort_info: 0
 
+/package_sets:
+    title: Writing the package sets
+    sort_info: 100
+

data/doc/guide/src/index.page

@@ -28,20 +28,22 @@ specification. More specifically, the package manifest files are common between
 ROS package management and autoproj (more details in the following of this
 document).
 
-Components of an Autoproj installation
+Overview of an autoproj installation
 -------------------------------------
-A autoproj installation is seeded by _package sets_. A package set is a local or remote
-directory in which there is:
 
- * a list of available packages, and information on how to build these packages.
-   This list, and the build information, are Ruby scripts that use the autobuild
-   API. [More ...](autobuild.html)
- * version control information: where to get the source code for each of the
-   packages defined in the set.
+The idea in an autoproj installation is that people share _definitions_ for a
+set of packages that can depend on each other. Then, anyone can cherry-pick in
+these definitions to build its own installation (in practice, one builds a
+complete configuration per-project).
 
-Then, an autoproj configuration is simply a list of package sets (i.e. a list of
-packages that are available to build), and a file that selects which packages
-should be built. This file is the <tt>manifest</tt>.
+Each package definition includes:
+
+ * how to get the package's source code
+ * how to build the package
+ * on what the package depends. This can be either another package built by
+   autoproj, or an operating system package.
+
+See [this page](structure.html) for more information.
 
 Bootstrapping
 -------------
@@ -97,6 +99,6 @@ As a guideline, we recommend that inter-package dependencies are managed by
 using pkg-config.
 
 To describe the package, and more importantly to setup cross-package
-dependencies, an optional manifest file can be added. This manifest file is
-named manifest.xml. Its format is described later in this user's guide.
+dependencies, [an optional manifest file can be
+added](package_sets/manifest-xml.html).
 

data/doc/guide/src/manifest.xml

@@ -0,0 +1,14 @@
+<package>
+  <description brief="one line of text">
+    long description goes here, 
+    <em>XHTML is allowed</em>
+  </description>
+  <author>Alice/alice@somewhere.bar, Bob/bob@nowhere.foo</author>
+  <license>BSD</license>
+  <url>http://sites.google.com/site/rubyinmotion</url>
+  <logo>http://sites.google.com/site/rubyinmotion</logo>
+
+  <depend package="pkgname"/> <!-- add dependency on another autoproj-built package -->
+  <depend package="common"/>
+  <rosdep name="python" /> <!-- add dependency on a prepackaged operating system package -->
+</package>

data/doc/guide/src/{autobuild.page → package_sets/autobuild.page}

@@ -29,17 +29,71 @@ end
 
 The above snippet being equivalent to calling <tt>cmake -DVAR=VALUE</tt>
 
-<b>Note to advanced users</b>
-<br />
-The "pkg" variable holds an object that represents the package. This
-object is an instance of the Autobuild::CMake. See [the autobuild
-API](http://doudou.github.com/autobuild/Autobuild/CMake.html) for more
-details.
-{.note}
-
-Defining autotools packages
+The "pkg" variable in the example above is an instance of
+[Autobuild::CMake](http://doudou.github.com/autobuild/Autobuild/CMake.html)
+{.block}
+
+Defining autotools packages {#autotools}
 ---------------------------
-TBD
+
+{coderay:: ruby}
+autotools_package "package_name"
+autotools_package "package_name" do |pkg|
+    pkg.configureflags << "--enable-feature" << "VAR=VALUE"
+    # additional configuration
+end
+{coderay}
+
+The 'pkg' variable in the example above is an instance of
+[Autobuild::Autotools](http://doudou.github.com/autobuild/Autobuild/Autotools.html)
+{.block}
+
+Defining Ruby packages
+----------------------
+
+{coderay:: ruby}
+ruby_package "package_name"
+ruby_package "package_name" do |pkg|
+    # additional configuration
+end
+{coderay}
+
+This package handles pure ruby libraries that do not need to be installed at
+all. Autoproj assumes that the directory layout of the package follows the following
+convention:
+
+ * programs are in bin/
+ * the library itself is in lib/
+ * if an extension needs to be built, a Rakefile has to be there with a "setup"
+   target to do the job.
+
+Defining oroGen packages
+------------------------
+
+{coderay:: ruby}
+orogen_package "package_name"
+orogen_package "package_name" do |pkg|
+    # customization code
+end
+{coderay}
+
+oroGen is a module generator for the Orocos component framework. See [the oroGen
+documentation](http://doudou.github.com/orogen) for more information.
+
+The 'pkg' variable in the example above is an instance of
+[Autobuild::Orogen](http://doudou.github.com/autobuild/Autobuild/Orogen.html)
+{.block}
+
+Custom package building
+-----------------------
+
+{coderay:: ruby}
+import_package "package_name" do |pkg|
+    pkg.post_install do
+        # add commands to build and install the package
+    end
+end
+{coderay}
 
 Declaring documentation targets
 -------------------------------
@@ -74,9 +128,21 @@ pkg.depends_on_os_package "package_name"
 
 Both methods should be used only for dynamic dependencies, i.e. dependencies
 that are dependent on build options (see below). Static dependencies should be
-defined in the package's manifest.xml
+defined in [the package's manifest.xml](manifest-xml.html)
 {.warning}
 
+Finally, it is possible to give aliases to a package's name, by using the
+Autobuild::Package#provides method. If one does
+
+{coderay:: ruby}
+cmake_package "mypkg" do |pkg|
+    pkg.provides "pkgconfig/libmypkg"
+end
+{coderay}
+
+then a package that declares a dependency on "pkgconfig/libmypkg" will actually
+depend on "mypkg".
+
 Defining and using options
 --------------------------
 

data/doc/guide/src/package_sets/importers.page

@@ -0,0 +1,164 @@
+---
+title: Package import
+sort_info: 250
+---
+
+As [we already mentioned](index.html), the source.yml file contains information
+on where to import the source packages from. This information is included in the
+version\_control field of the source.yml, and is of the general form:
+
+{coderay:: yaml}
+version_control:
+    package_name:
+        vcs_def
+    package_name:
+        vcs_def:
+{coderay}
+
+Autoproj follows the following rules to find the importer definition for a given
+package:
+ 
+ - it looks *in order* in the package sets listed in the manifest file, and will
+   take the definition from the *first* package set that has a definition for
+   the package.
+ - in the source.yml file, it will match the package's name with the
+   package\_name fields. It will consider every matching block (i.e. every
+   package\_name that matches), overriding earlier options by later ones.
+
+As an example, let's consider the following manifest:
+
+{coderay:: ruby}
+package_sets:
+    - rubim.drivers
+    - rubim.orocos
+    - rubim.base
+{coderay}
+
+Now, let's assume that the rubim.orocos package set has a source.yml file with:
+
+{coderay:: ruby}
+version_control:
+    orocos/:
+        type: git
+        url: git://github.com/$PACKAGE.git
+    orocos/orocos.rb:
+        branch: roby
+{coderay}
+
+Finally, the rubim.drivers package set has:
+
+{coderay:: ruby}
+version_control:
+    orocos/logger:
+        type: git
+        url: git://github.com/$PACKAGE.git
+        branch: perf
+{coderay}
+
+Then, the following will happen:
+
+ * all packages that are prefixed with "orocos/" will match the general
+   definition of rubim.orocos.
+ * in addition, the 'branch' flag of orocos/orocos.rb will be overriden from
+   'master' (the default) to 'roby'
+ * in the case of orocos/logger, since there is a matching definition in
+   rubim.drivers, the definition in rubim.orocos *is not used at all*. Only the
+   definition found in rubim.drivers' source.yml file matters.
+
+The remaining of this page will detail the various options that exist to import
+a source package.
+
+Git {#all_importers}
+\--- 
+
+The general setup for git imports is:
+
+{coderay:: yaml}
+version_control:
+    package_name:
+        type: git
+        url: repository_url_or_path
+        branch: branch_name
+        tag: tag_name # it is branch OR tag
+{coderay}
+
+Autoproj will maintain an 'autobuild' remote on the checked out repository:
+i.e., it will make sure that the URL of this remote is always linked to the
+right URL from the config file, and will update the relevant branch on update
+(beware: the other branches won't get updated).
+
+Moreover, autoproj will make sure that updating your local repository always
+resolves as a fast-forward (i.e., it will never create a merge)
+
+Subversion
+----------
+
+The general setup for subversion imports is:
+
+{coderay:: yaml}
+version_control:
+    package_name:
+        type: svn
+        url: repository_url_or_path
+{coderay}
+
+Note that the repository *must* be accessible without any password, and the
+import will fail if a password was needed.
+{.warning}
+
+Tar archives
+------------
+
+{coderay:: yaml}
+version_control:
+    package_name:
+        type: archive
+        url: http://sourceforge.net/blablabla.tar.gz?option=value
+        filename: blabla.tar.gz # Optional: if the file name cannot be inferred from the URL
+        no_subdirectory: false # Optional. Set to true if there is not a leading directory in the archive
+        update_cached_file: false # Optional. Set to false to disable automatic updates
+{coderay}
+
+The importer expects that there is a leading subdirectory in the archive, under
+which all files. If that is not the case, i.e. if all files are in the root of
+the archive, do not forget to set the no\_subdirectory option.
+
+Autoproj tries to guess what is the name of the downloaded file by extracting it
+out of the URL. Sometimes, this does not work as the URL does not fit the
+expected scheme -- in these cases you will get a tar error on update. To
+override this autodetection behaviour, set the filename option to the actual
+downloaded file name.
+
+By default, autoproj will check if the downloaded file has been updated on the
+server, and will download it again if it is the case. If you are downloading
+release tarballs, this is unneeded as the archive should not be updated. In that
+case, set the update\_cached\_file option to false to save the time needed to
+check for the update (can be long on, for instance, sourceforge). The source
+will of course be updated if you change the URL (i.e. to download a new release
+of the same software).
+
+Patching the source once it is checked out/updated
+--------------------------------------------------
+
+It is possible to apply patches after a given package (imported by any of the
+importer types) has been checked out/updated. To do so, simply add a
+<tt>patches:</tt> option in the importer configuration, that lists the patches
+to apply:
+
+{coderay:: yaml}
+version_control:
+    package_name:
+        type: archive
+        url: http://sourceforge.net/blablabla
+        patches:
+            - $AUTOPROJ_SOURCE_DIR/blablabla-01.patch
+            - $AUTOPROJ_SOURCE_DIR/blablabla-02.patch
+{coderay}
+
+Note that in the example above, the patch is saved in the package set's folder
+(the value of AUTOPROJ_SOURCE_DIR). This is a highly required practice.
+
+Note that if the patch list changes (i.e. the *names* change), autoproj will
+automatically unpatch and repatch as required. It is therefore highly required
+to change the patch name if the patch changes.
+

data/doc/guide/src/{source_yml.page → package_sets/index.page}

@@ -1,5 +1,5 @@
 ---
-title: Creating a package set
+title: Overview
 sort_info: 100
 ---
 A package set is made of three things:
@@ -35,6 +35,8 @@ For the first step, you need to add one of the following lines:
 cmake_package "my/package" # for CMake package
 autotools_package "my/package" # for autoconf/automake packages
 orogen_package "my/package" # for orogen packages
+import_package "my/package" # for custom packages
+ruby_package "my/package" # for ruby libraries (optionally with C/C++ extensions)
 {coderay}
 
 The package name will be used to refer to this particular package later on --
@@ -76,7 +78,7 @@ version_control:
   - my/package: none
 {coderay}
 
-The remaining of this page is a more in-depth description of this process.
+See [this page](importers.html) for details on the import mechanisms.
 
 Autobuild scripts
 -----------------
@@ -87,6 +89,9 @@ form, it looks like:
 {coderay:: ruby}
 cmake_package "orocos/rtt"
 autotools_package "drivers/imu"
+orogen_package "modules/imu"
+import_package "external/sisl"
+ruby_package "orocos/orocos.rb"
 {coderay}
 
 The above snippet defines two packages. The first one uses CMake as a build

data/doc/guide/src/package_sets/manifest-xml.page

@@ -0,0 +1,29 @@
+---
+title: The manifest.xml file
+sort_info: 120
+---
+
+The manifest.xml is an optional (but *very recommended*) file that lies in the
+root of every source package. This file describes both what the package *is*
+(i.e. short description, contact information), and dependency information (what
+should be installed for that package to be built successfully).
+
+The general form of the file is:
+
+{coderay:: xml}
+<package>
+  <description brief="one line of text">
+    long description goes here, 
+    <em>XHTML is allowed</em>
+  </description>
+  <author>Alice/alice@somewhere.bar, Bob/bob@nowhere.foo</author>
+  <license>BSD</license>
+  <url>http://sites.google.com/site/rubyinmotion</url>
+  <logo>http://sites.google.com/site/rubyinmotion</logo>
+
+  <depend package="pkgname"/> <!-- add dependency on another autoproj-built package -->
+  <depend package="common"/>
+  <rosdep name="python" /> <!-- add dependency on a prepackaged operating system package -->
+</package>
+{coderay}
+