autoproj 1.7.0.rc2 → 1.7.0

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

@@ -1,239 +0,0 @@
----
-title: Writing autobuild scripts
-sort_info: 200
----
-
-Defining CMake packages
------------------------
-A simple cmake package is defined with
-
-{coderay:: ruby}
-cmake_package "package_name"
-{coderay}
-
-More complex tweaking is achieved with
-
-{coderay:: ruby}
-cmake_package "package_name" do |pkg|
-  [modify the pkg object]
-end
-{coderay}
-
-In particular, cmake build options can be given with
-
-{coderay:: ruby}
-cmake_package "package_name" do |pkg|
-  pkg.define "VAR", "VALUE"
-end
-{coderay}
-
-The above snippet being equivalent to calling <tt>cmake -DVAR=VALUE</tt>
-
-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}
----------------------------
-
-{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 a Rakefile is present in the root of the source package, its <tt>default</tt>
-task will be called during the build, and its <tt>redocs</tt> task will be used
-for documentation generation. The <tt>rake_setup_task</tt> and
-<tt>rake_doc_task</tt> package properties can be used to override this default
-setting:
-
-{coderay::ruby}
-ruby_package "package_name" do |pkg|
-    pkg.rake_setup_task = "setup"
-    pkg.rake_doc_task = "doc:all"
-end
-{coderay}
-
-Additionally, they can be set to <tt>nil</tt> to disable either setup or documentation
-generation. For instance, the following code disables documentation generation
-and uses the +setup+ task at build time:
-
-{coderay::ruby}
-ruby_package "package_name" do |pkg|
-    pkg.rake_setup_task = "setup"
-    pkg.rake_doc_task = nil
-end
-{coderay}
-
-The 'pkg' variable in the example above is an instance of
-[Autobuild::ImporterPackage](http://doudou.github.com/autobuild/Autobuild/ImporterPackage.html),
-with additional methods coming from [the RubyPackage
-module](http://doudou.github.com/autoproj/api/Autoproj/RubyPackage.html)
-{: .block}
-
-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}
-
-OS-specific bits (<tt>not_on</tt> and <tt>only_on</tt>) {#not_on_and_only_on}
-----------------
-It is possible to have some parts of the autobuild file be OS-specific. Two
-calls are made available for that.
-
-First, if you know that some packages should not be built on some operating
-systems, you should enclose their declaration in a 'not_on' statement. For
-instance:
-
-{coderay:: ruby}
-not_on 'debian' do
-  cmake_package 'excluded_package'
-end
-{coderay}
-
-It is additionally possible to select specific versions
-
-{coderay:: ruby}
-not_on 'debian', ['ubuntu', '10.04'] do
-  cmake_package 'excluded_package'
-end
-{coderay}
-
-If, on the other hand, you want some bits to be available only **on** a specific
-OS, use the only_on statement:
-
-{coderay:: ruby}
-only_on ['ubuntu', '10.04'] do
-  cmake_package 'only_ubuntu'
-end
-{coderay}
-
-If the user tries to build a package that is excluded on his architecture, he
-will get the following error message:
-
-modules/dynamixel depends on drivers/dynamixel, which is excluded from the build: drivers/dynamixel is disabled on this operating system
-{: .cmdline}
-
-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
--------------------------------
-Both autotools and cmake packages use <tt>make</tt> as the low-level build tool.
-For both packages, you can declare a documentation target that will be used
-during the call to <tt>autoproj doc</tt> to generate documentation:
-
-{coderay:: ruby}
-cmake_package "package_name" do |pkg|
-  pkg.with_doc 'doc'
-  pkg.doc_dir = "doc/html"
-end
-{coderay}
-
-The <tt>doc_dir</tt> assignment above is needed if the package installs its documentation
-elsewhere than "doc".
-
-Defining dependencies
----------------------
-Inter-package dependencies can be defined with
-
-{coderay:: ruby}
-pkg.depends_on "package_name"
-{coderay}
-
-Where package name is either the name of another autoproj-built package, or the
-name of a package that is to be [provided by the operating system](osdeps.html).
-
-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](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
---------------------------
-
-It is possible to define configuration options which are set by your user at
-build time. These options can then be used in the autobuild scripts to
-parametrize the build.
-
-The general form of an option declaration is:
-
-{coderay:: ruby}
-configuration_option "option_name", "option_type",
-    :default => "default_value",
-    :values => ["set", "of", "possible", "values"],
-    :doc => "description of the option"
-{coderay}
-
-Once declared, it can be used in autobuild scripts with:
-
-{coderay:: ruby}
-user_config("option_name")
-{coderay}
-
-Options are saved in <tt>autoproj/config.yml</tt> after the build. Options that
-are already set won't be asked again unless the <tt>--reconfigure</tt> option is
-given to <tt>autoproj build</tt>.
-
-Do not try to have too many options, that is in general bad policy as
-non-advanced users won't be able to know what to answer. Advanced users will
-always have the option to override your autobuild definitions to tweak the
-builds to their needs.
-{: .warning}
-

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

@@ -1,165 +0,0 @@
----
-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 loads the information contained in the version_control section of the
-   package set that defines the considered package
- - it will apply any modification that is contained in the overrides section by
-   the package sets listed *after* the aforementionned package set
-
-For both the version_control and overrides section, autoproj 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 setup by later
-ones.
-
-As an example, let's consider the following manifest:
-
-{coderay:: ruby}
-package_sets:
-    - rubim.base
-    - rubim.orocos
-    - rubim.drivers
-{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}
-overrides:
-    - orocos/logger:
-        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
-   the overrides section of rubim.drivers, the 'perf' branch will be checked out
-   instead of the 'roby' branch, keeping the same importer type and URL
-
-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/package_sets/index.page

@@ -1,223 +0,0 @@
----
-title: Overview
-sort_info: 100
----
-A package set is made of three things:
-
- * the description file (source.yml)
- * an optional initialization script (init.rb) and override script
-   (overrides.rb)
- * autobuild scripts (\*.autobuild)
-
-Starting a new package set
---------------------------
-
-Create a subdirectory in autoproj/ and add a source.yml file that looks like:
-
-{coderay:: yaml}
-name: my_package_set_name
-{coderay}
-
-Et voila ! You have a new empty package set
-
-Adding a package
-----------------
-
-Adding a package to a package set involves changing two files:
-
- * one of the package set's autobuild file that declares what packages there
-   are. Any file ending with .autobuild is loaded as an autobuild file by
-   autoproj.
- * the package set's source.yml file that declares where to get it (version
-   control information)
-
-For the first step, you need to add one of the following lines:
-
-{coderay:: ruby}
-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 --
-especially for version control definition. If subdirectories are used, like "my"
-in the above example, the package source will be checked out and built in the
-corresponding subdirectory. For instance, with
-
-{coderay:: ruby}
-cmake_package "drivers/hokuyo"
-{coderay}
-
-the hokuyo driver will _always_ be built in a <tt>drivers/</tt> subdirectory.
-
-Now that the package is declared, we need to add version control information to
-the source.yml file. This needs to be done in the version\_control section of
-the file, as for instance:
-
-{coderay:: yaml}
-version_control:
-  - my/package:
-      type: git
-      url: git://github.com/blabla/my-package.git
-{coderay}
-
-The corresponding subversion definition would be:
-
-{coderay:: yaml}
-version_control:
-  - my/package:
-      type: svn
-      url: svn+ssh://svnhosting.com/blabla/trunk/my/package
-{coderay}
-
-For testing purposes, it is possible to tell autoproj to *not* take into account
-any VCS information:
-
-{coderay:: yaml}
-version_control:
-  - my/package: none
-{coderay}
-
-See [this page](importers.html) for details on the import mechanisms.
-
-Autobuild scripts
------------------
-The autobuild scripts lists all the packages defined by this set. It is a
-Ruby script (but you don't need to know Ruby to write one). In its most simple
-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
-system and will be installed in the <tt>orocos/rtt</tt> subdirectory of the
-autoproj installation. The second one is an autotools package. There is, for
-now, only support for these two build systems, and for Ruby packages. Package
-definitions can be tweaked quite a lot, including the ability to generate
-documentation. See [the next page](autobuild.html) for more information on how to write autobuild
-scripts.
-
-source.yml
-----------
-The source.yml file gives generic information on the package set itself (most
-importantly its name), and version control information (i.e. where to get the
-packages). It is a YAML file, and looks like:
-
-{coderay:: yaml}
-name: dfki.orocos
-constants:
-  ROOT_DIR: $HOME/share
-  
-version_control:
-  - "modules/.*":
-      type: git
-      url: $ROOT_DIR/$PACKAGE.git
-  - "drivers/.*":
-      type: svn
-      url: svn+ssh://rlbsvn.informatik.uni-bremen.de/trunk/$PACKAGE.git
-{coderay}
-
-The name field gives a name for the set. It is arbitrary, but the guideline
-is to give a name that is java-like for namespaces, i.e. origin.name.
-
-The <tt>constants:</tt> section lists values that can be reused for different
-packages. Autoproj defines two constants:
- 
- * HOME is the user's home directory,
- * PACKAGE is the actual package name, useful when using wildcards in package
-   names (see below)
-
-It is also possible to use configuration variables, that get asked to the user
-during the build (see below).
-
-Finally, the <tt>version_control:</tt> section describes how to import each
-software package. Its general format is:
-{coderay:: yaml}
-package_name:
-  type: version_control_type # git, svn, cvs, darcs
-  url: repository_url
-{coderay}
-
-Where package\_name is a regular expression that matches the package name (for
-instance, ".\*" will match all packages and "drivers/.\*" will match packages
-whose name starts with 'drivers'). The package name is the one given to the
-<tt>blabla_package</tt> stanza in the autobuild file.
-
-For the git importer, one of 'branch' or 'tag' options can be provided as well:
-{coderay:: yaml}
-package_name:
-  branch: branch_to_track
-  tag: tag_to_stick_to # it is branch OR tag
-{coderay}
-
-The options are applied in order, meaning that the top entries will be overriden
-by the lower ones. In general, one will have a ".\*" entry to give options for
-all packages, and then override for specific packages:
-
-{coderay:: yaml}
-version_control:
-  - .*: # common options for all packages
-      type: git
-      url: $ROOT_DIR/$PACKAGE.git
-
-  - "modules/logger": # we don't follow master on this module
-      branch: imoby
-{coderay}
-
-Interaction between package sets definition files
--------------------------------------------
-When multiple package sets are used, it is possible to override the version
-control definitions in low-priority sets with a higher priority one. Autoproj
-has the following rules when searching for version control information:
-
- * autoproj looks at the package sets *in the order they appear in the
-   installation manifest*
- * autoproj searches a relevant version\_control field, and stops at the first
-   package set that has one.
- * autoproj *stops searching* at the package set that defines the package.
-   Consequence: this set *must* have a version\_control field for it, and an
-   error will be issued otherwise.
-
-Using configuration options
----------------------------
-autoproj offers a configuration system that allows the user to tweak the build
-to its needs. If the version control definitions depend on such configuration
-options (as, for instance, because you want to parametrize the importer URLs),
-then create an init.rb file next to the source.yml file, and add lines looking
-like:
-
-{coderay:: ruby}
-configuration_option "option_name", "option_type",
-    :default => "default_value",
-    :values => ["set", "of", "possible", "values"],
-    :doc => "description of the option"
-{coderay}
-
-where the option\_type field can either be "string" or "boolean".
-
-Then, you can use the option\_name as an expansion in the source.yml file.
-
-For instance, at my lab we are using an share filesystem to store the git
-repositories. Our project's init.rb file has the following option definition:
-{coderay:: ruby}
-configuration_option "MOUNT_POINT", "string",
-    :default => "$HOME/nfs",
-    :doc => "mount point of the NFS server"
-{coderay}
-
-And the source.yml uses it with:
-
-{coderay:: yaml}
-version_control:
-  ".*":
-    url: $MOUNT_POINT/git/$PACKAGE.git
-    type: git
-{coderay}
-