autobuild 0.5.1 → 0.6

data/CHANGES

@@ -1,4 +1,13 @@
-= Autobuild changelog
+= Autobuild ChangeLog
+
+== Version 0.6
+
+Use a Ruby-based DSL instead of YAML config files. It is waaaaaay more
+powerful and waaay cleaner. See demo.rb for an example
+
+* Added the Darcs importer
+* Fixes in dependency handling
+* Uses Rake 0.7
 
 == Version 0.5.1
 
@@ -6,8 +15,6 @@ Fixes the release process, in which the bin/ directory was not distributed
 
 * 0.5 gem did not include bin/autobuild (which obviously was not good). Fix that
 
-
-
 == Version 0.5
 
 Fixes the mail default behaviour. Added the 'tar' importer.

data/README

@@ -1,305 +1,138 @@
 = Introduction
+
+== WARNING for 0.5 users
+Old configuration files used with autobuild 0.5 aren't accepted by Autobuild 0.6. Since 0.6, Autobuild 
+uses Ruby for configuration (just like rake does)
+
 == What's autobuild ?
 Autobuild is a builder for a set of software packages. It takes as input a yaml config file as input and
 
 * imports the package from a SCM or (optionnaly) updates it
-* configures it (for instance for autoconf-based packages)
-* builds and installs it
-
-It takes the dependencies between packages into account in its build process.
-
-== Example config explained
-
-1.  This section is not used at all by autobuild. It is only here to define references 
-    used in the reste of the config file
-
-        defines:
-          openrobots: ':ext:sjoyeux@cvs.laas.fr/cvs/openrobots'
-          openprs_cvs: ':ext:sjoyeux@cvs.laas.fr:/usr/local/openprs/CVS-Repository'
-          global_prefix: /home/doudou/laas/openrobots
-          srcdir: ${global_prefix}/tools
-          prefix: ${global_prefix}/build/tools
-
-2.  <tt>autobuild</tt> holds the configuration of the build tool itself. See the
-    <b>Autobuild configuration</b> section for the available configuration options.
-
-        autobuild:
-          srcdir: $srcdir
-          prefix: $prefix
-          clean_log: true
-        
-          mail:
-            to: sjoyeux@laas.fr
-        
-          environment:
-            PATH: [ "/bin", "/usr/bin" ]
-            LD_LIBRARY_PATH:
-            PKG_CONFIG_PATH:
-
-3.  +programs+ defines the tools autobuild should use instead of the its default values.
-    See each the rest of the documentation to know what values are used.
-
-        programs:
-           aclocal: "aclocal-1.9"
-           automake: "automake-1.9"
-
- 
-4.  the +packages+ sections is where packages are defined
-
-        packages:
-
-5.  options in <tt>common</tt> are merged in each package configuration. See 
-    <b>Configuring packages</b> for the detailed merging rules.
-
-            config:
-                prefix: ""
-
-6.  Tell autobuild to build the pocolibs package. Two common options here: 
-    *type*::    the builder to use. Available package types are currently +autotools+,
-                +import+ and +genom+ (a tool used at my lab;)). See the <b>Available
-                package types</b> section for their configuration.
-    *import*::  the importer to use. Source definition for the importer is always in 
-                the +source+ option.
-    
-            pocolibs:
-                type: autotools
-                import: cvs
-                source: [ $openrobots, pocolibs ]
-
-   
-7. Autobuild takes the dependencies between packages into account. Just list in +depends+ 
-   the packages which should be installed before this one is built.
-
-            genom:
-                type: autotools
-                import: cvs
-                source: [ $openrobots, genom ]
-                depends: pocolibs
-
-
-
-
-
-= Configuration file
-
-The config file is {a Yaml file}[http://yaml4r.sourceforge.net/cookbook]. It is a hash where 
-each element is a section:
-
-  section1:
-    option1: value
-    option2: value
-  section2:
-
-In the documentation, I'll sometime use paths to reference the config options. For instance, 
-+option1+ is <tt>section1/option1</tt>. The +to+ option in the configuration example
-is <tt>autobuild/mail/to</tt>
-  
-Autobuild uses three sections:
-
-<b>autobuild</b>::   main autobuild configuration. See <b>Autobuild configuration</b> below
-*programs*::                the programs used by importers and builders. See each tool 
-                            documentation for the list of used options
-*packages*::                the list of packages to build. See <b>Package configuration</b> below
-*defines*::                 this is used for variable interpolation. Any key/value pair defined in
-                            this section can be used later in other parts of the config files using
-                            the $key or ${key} notation
-
-== Autobuild configuration (<tt>autobuild</tt>)
-=== Misc options
-*update*::    if false, do not update the packages that are already imported (default: true). You
-              can also use the <tt>--no-update</tt> on the command line
-
+* configures it. This phase can handle code generation, configuration (for instance for autotools-based
+packages), ...
+* build
+* install
+
+It takes the dependencies between packages into account in its build process, updates the needed environment
+variables (+PKG_CONFIG_PATH+, +PATH+, +LD_LIBRARY_PATH+, ...)
+
+== Available packages
+=== Common usage
+All package objects define the following attributes
+*importer*:: the importer object (see "Available importers" below)
+*srcdir*:: where the package sources are located. If it is a relative
+	   path, it is relative to the value of Autobuild.srcdir. The default is to
+	   use the package name. 
+*prefix*:: the directory where the package should be installed. If it is a relative
+	   path, it is relative to the value of Autobuild.prefix. The default is to
+	   use the package name. 
+
+Each package method (Autobuild.import, Autobuild.autotools, ...) takes either a package
+name for first argument, or a <tt>name => dependency_array</tt> hash, and take a block which
+can be used to configure the package. For instance
+    Autobuild.import :my_package do |pkg|
+	pkg.srcdir = 'my_package_dir'
+    end
+
+    Autobuild.import :my_package => [:depends, :depends_also] do |pkg|
+    end
+
+=== Source only
+    package = Autobuild.import(dependencies) do |pkg|
+	<package configuration>
+    end
 
-=== Directories (<tt>autobuild/srcdir</tt>, <tt>autobuild/prefix</tt> and <tt>autobuild/logdir</tt>)
-*srcdir*::    the path where programs are to be imported. See <b>Packages configuration</b> for 
-              more information on how this option is used.
-*prefix*::    the path where programs are to be installed. See <b>Packages configuration</b> for more 
-              information on how this option is used.
-*logdir*::    by default, autobuild does not displays the output of each subcommand it launches. 
-              Insteads, it saves this output in log files. These log files are saved in +logdir+. 
-              The default value is <tt>prefix/autobuild</tt>
-<b>clean_log</b>:: if we must remove all logfiles before each autobuild run or if we should append to them. The
-                   default is +true+, that is log files are removed. Note that if mailing is active, all log 
-                   files are attached to notification mail.
-*nice*::      The priority at which autobuild should launch subprocesses
-
-
-=== Environment (<tt>autobuild/environment</tt>)
-The <tt>autobuild/environment</tt> section lists the initial values for 
-the environment variables. While packages builders shall update the environment 
-variables as needed, you can have to set up a proper initial environment. Arrays 
-are converted into strings by joining elements by ':'
-
-For instance
-    autobuild:
-          environment:
-            PATH: [ "/bin", "/usr/bin" ]
-            LD_LIBRARY_PATH:
-            PKG_CONFIG_PATH:
-
-sets
-
-    PATH="/bin:/usr/bin"
-    LD_LIBRARY_PATH=""
-    PKG_CONFIG_PATH=""
-
-
-=== Mail (<tt>autobuild/mail</tt>)
-Use this options if you want to receive a mail when the build has finished (on success and failures)
-
-    autobuild:
-        mail: true
-
-Valid options are:
-*to*::   the mail destination, default is <tt>user@hostname</tt> (for instance sylvain@localhost for a user 'sylvain')
-*from*:: the mail source, default is <tt>user@hostname</tt>
-*smtp*:: the stmp server to use. Default is +localhost+
-*port*:: the port the server is running on. Default is the smtp port (25)
-
-All log files relative to the current build are attached to the mail.
-
-
-== Configuring packages (<tt>packages/*</tt>)
-=== The <tt>packages/config</tt> section
-If you want to add common options in each package, just set it them here. Note that the options
-are /merged/ in the package config. It neither replaces the values in the package nor the package 
-options replaces them. The merging strategy depends on the way the option is specified in this common section:
-* if it is an array, the package option is converted to an array and the common options are appended
-* if it is a string, the package option is converted to a string and the common option are appended
-with a space inserted between the two
-* if it is a boolean value, it is <em>overriden</em> by the package value
-* any other values are forbidden
+Use +import+ if you need the package sources but don't need to build it. You just need
+to set +importer+ and +srcdir+. +prefix+ is ignored.
 
-To ease the config file writing, all options that accept arrays also accept a string when there 
-is only one element. <b>Do not</b> do that in the <tt>common</tt> option.
+=== Autotools
+    package = Autobuild.autotools(name, dependencies) do |pkg|
+	<package configuration>
+    end
 
-=== Package definition
-All subsections of the <tt>packages/</tt> section but <tt>common</tt> are package definitions
-The section name is used as the package name. The package definition sets up the importer to get the
-source and the builder to build and install it.
+Use this to build GNU autotools-based packages. This handles autoconf-only packages as 
+well as those using automake
 
-*type*::    the package type. See the <b>Available package types</b> sections
+Options to give the +configure+ script are given in the +configureflags+ array
+    pkg.configureflags = ['--with-blah', 'FOO=bar' ]
 
-*srcdir*::  where sources are to be imported. If this is a relative path, it is relative to the global
-            <tt>/autobuild/srcdir</tt> option. Otherwise, the absolute path is used. If no +srcdir+
-            is given, the package name is used, so that the default import dir is 
-            <em>global srcdir</em>/<em>package_name</em>.
-        
-            *Note* because of most SCM operations, it is forbidden that two packages have the same srcdir.
-            Empty srcdir are forbidden for the same reason.
+If you want the files produced during the build to be separated from the source files, set the +builddir+ attribute.
+For now, it has to be a relative path, relative to the source directory.
+    pkg.builddir = 'build'
 
-*importer*::    
-            the importer type. For now, only +cvs+ and +svn+ are available. See the <b>Available importers</b>
-            section.
+The generation of the configure script uses four programs: +autoheader+, +autoconf+, +aclocal+, 
++automake+. The default program path can be overriden in the Autotools.programs hash. For
+instance, to be sure that <tt>automake-1.9</tt> is used <bb>for all packages</bb>, you set
 
-*patch*::   the list of patch we should apply. Patches are applied in order, with -p0. Autobuild
-            remembers the list of already applied patches, and will handle the changes to this list gracefully.
-            Since relative paths for patch files are relative to the autobuild working directory, I recommend 
-            you put absolute paths here.
+    Autotools.programs['automake'] = 'automake-1.9'
 
-*source*::  where the importer should get the sources. The format of this options depends on
-            the importer used. See Available importers.
+Autobuild tries to detect what tools it should run, but you can override. Autodetection works
+as follows:
+* if a script named +autogen+ or +autogen.sh+ exists in the package source directory, it is run
+  and the other tools are not. The name of this kind of script can be set by calling Autotools#use
+    pkg.use :autogen => 'my_autogen_script'
+* +autoheader+ is never used by default
+* +autoconf+ is used if there is <tt>configure.ac</tt> or <tt>configure.in</tt> in the source dir
+* +aclocal+ is used if +autoconf+ is enabled (either explicitely or by autodetection)
+* +automake+ is used if there is a <tt>Makefile.am</tt> file in the source dir
+* you can force to enable or disable any of these steps by calling Autotools#use. Set it to +true+
+  to force its usage, +false+ to disable it or to a string to force the usage of a particular program
+    pkg.use :autogen => false
+    pkg.use :automake => false
+    pkg.use :autoheader => true
+    pkg.use :autoconf => 'my_autoconf_program'
 
-*prefix*::  where the program is to be installed. If this is a relative path, it is relative to the global
-            <tt>/autobuild/prefix</tt> option. Otherwise, the absolute path is used. If no prefix
-            is given, the package name is used, so that the default install dir is 
-            <em>global prefix</em>/<em>package name</em>
+  The 'autogen' option cannot be set to +true+.
 
-*depends*::     the array of packages that should be built and installed before this one is built. <tt>depends: [ foo ]</tt>
-                is equivalent to <tt>depends: foo</tt>. To make the use of +depends+ in the <tt>common</tt> 
-                section possible, this package name is automatically removed from the package +depends+ array.
-*provides*::    defines aliases for this package. As for +depends+, an array with only element can be replaced
-                by the simple value.
+The only program used during the build and install phases is +make+. Its path can be overriden 
+in the Autobuild.programs hash
+    Autobuild.programs['make'] = 'gnumake'
 
 == Available importers
-=== CVS (<tt>type: cvs</tt>)
-*source*::  the source specification is a [ repository, module ] array
-*cvsup*::   options to add to cvs up. Defaults to '-dP'
-*cvsco*::   options to add to cvs ci, Defaults to -P
-
-=== Subversion (<tt>type: svn</tt>)
-*source*::  the svn URL. To ease the Yaml nodes reference (the <tt>*ref</tt> form), it can be an array
-            which is then converted into a path by joining the elements with '/'. For instance:
-    
-                packages:
-                    foo:
-                        import: svn
-                        source: [ $my_home_repository, /trunk/foo ]
-
-*svnup*::   options to add to svn up. Defaults to ''
-*svnco*::   options to add to svn co. Defaults to ''
+You must set an importer object for each package. The package importer is the +importer+ attribute
+and is set via <tt>package.importer = my_importer</tt>. An importer +foo+ is defined by the class
+Autobuild::FooImporter and defines a Autobuild.foo method which creates a new importer object.
+Importer classes files are in <tt>lib/autobuild/import/</tt>
 
-=== Tar (<tt>type: tar</tt>)
-This importer gets a tarball file, which may be on a remote server, and un-tars
-it. For now, it cannot determine itself what is the directory included in the tarball,
-so you should set the srcdir: appropriately.
+=== CVS 
 
-For instance, a tarball with one directory <tt>package-0.1</tt> in it will 
-need a <tt>srcdir</tt> option of <tt>package-0.1</tt>. If you do 
-not set +srcdir+, autobuild will untar the package in the global srcdir
-(as intended) but will search for <tt>$global_srcdir/package</tt>
+    package.importer = cvs(cvsroot, module[, options])
 
-*source*::   the source URL. For now, http, ftp and file URLs are supported
-*cachedir*:: the directory where the local copy of the file should be saved 
-             (for http and ftp URLs only)
+Where +options+ is an option hash. See also Autobuild::CVSImporter and Autobuild.cvs
 
+* the default CVS command is +cvs+. It can be changed by
+    Autobuild.programs['cvs'] = 'my_cvs_command'
+* the default checkout option is <tt>-P</tt>. You can change that by giving a +cvsco+ option
+    cvs cvsroot, module, :cvsco => ['--my', '--cvs', '--options']
+* the default update option is <tt>-dP</tt>. You can change that by giving a +cvsup+ option
+    cvs cvsroot, module, :cvsup => ['--my', '--cvs', '--options']
 
+=== Subversion
+    package.importer = svn(url[, options])
 
-== Available package types (<tt>packages/</tt><em>name</em><tt>/type</tt>)
-=== Source only (<tt>type: import</tt>)
-Use +import+ if you need the package sources but don't need to build it. You just need
-to set up the importer and +srcdir+. +prefix+ is ignored.
-
-    packages:
-        bar:
-            type: import
-            import: cvs
-            source: [ $my_repository, "bar" ]
-            srcdir: bar
-
-=== Autotools (<tt>type: autotools</tt>)
-Use this to build GNU autotools-based packages. This handles autoconf-only packages as 
-well as automake-based packages.
-
-==== Configuration programs
-The <tt>autotools</tt> packages use four programs: *autoheader*, *autoconf*, *aclocal*, 
-*automake*. The default values can be overriden in the <tt>/programs</tt> section. For 
-instance, to be sure that automake 1.9 is used, you set
-
-    programs:
-        automake: automake-1.9
-
-Autobuild tries to detect what tools it should run
-* +autoheader+ is never used by default
-* +autoconf+ is used if there is <tt>configure.ac</tt> or <tt>configure.in</tt> in the imported dir
-* +aclocal+ is used if +autoconf+ is enabled (either explicitely or by autodetection)
-* +automake+ is used if there is a <tt>Makefile.am</tt> file in the imported dir
-* you can force to enable or disable any of these four tools in each package config by setting the tool
-  flag to true or false. For instance, if you don't want package +foo+ to use automake, you say
+Where +options+ is an option hash. See also Autobuild::SVNImporter and Autobuild.svn
 
-    packages:
-        foo:
-            automake: false
+* the default Subversion command is +svn+. It can be changed by
+    Autobuild.programs['svn'] = 'my_svn_command'
+* by default, no options are given to checkout. You add some by giving a +svnco+ option
+    svn url, :svnco => ['--my', '--svn', '--options']
+* by default, no options are given to update. You can add some by giving a +svnup+ option
+    svn url, :svnup => ['--my', '--svn', '--options']
 
-==== Build programs
-The only program used during the build phase is +make+. The make command can too be overriden in the
-<tt>programs</tt> section.
+=== *Darcs*
+    package.importer = darcs(url[, options])
 
-    programs:
-        make: gnumake
+Where +options+ is a hash. See also Autobuild::DarcsImporter and Autobuild.darcs
 
-==== Other options
-*builddir*::    the directory where the build takes place. For now, it has to be a relative path,
-                which will be considered relative to the source directory.
-*configureflags*::  array of options to add to the +configure+ command line
-                        configureflags: [ --with-bar-source=$srcdir/$bar_srcdir ]
-                        depends: bar
+* the default Darcs command is +darcs+. It can be changed by
+    Autobuild.programs['darcs'] = 'my_svn_command'
+* by default, no options are given to get. You add some by giving a +get+ option
+    darcs url, :get => ['--my', '--darcs', '--options']
+* by default, no options are given to pull. You can add some by giving a +pull+ option
+    darcs url, :pull => ['--my', '--darcs', '--options']
 
-= Running autobuild in daemon mode
-The <tt>--daemon</tt> command line options makes autobuild go into daemon mode.
- 
 = Copyright and license
 Author::    Sylvain Joyeux <sylvain.joyeux@m4x.org>
-Copyright:: Copyright (c) 2005 Sylvain Joyeux
+Copyright:: Copyright (c) 2005-2006 Sylvain Joyeux
 License::   GPL
 

data/Rakefile

@@ -1,7 +1,5 @@
 # Rakefile for Autobuild
-# Copyright 2005 by Sylvain Joyeux (sylvain.joyeux@m4x.org)
 
-# Based on the Rakefile for MetaProject
 # Copyright 2005 by Aslak Hellesoy (aslak.hellesoy@gmail.org)
 # All rights reserved.
 
@@ -26,7 +24,8 @@ require 'rake/rdoctask'
 #
 # REMEMBER TO KEEP PKG_VERSION IN SYNC WITH THE CHANGES FILE!
 PKG_NAME = "autobuild"
-PKG_VERSION = "0.5.1"
+UNIX_NAME = "autobuild"
+PKG_VERSION = "0.6"
 PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
 PKG_FILES = FileList[
   'bin/*',
@@ -40,12 +39,9 @@ task :default => [:gem]
 # Create a task to build the RDOC documentation tree.
 rd = Rake::RDocTask.new("rdoc") do |rdoc|
   rdoc.rdoc_dir = 'html'
-#  rdoc.template = 'kilmer'
-#  rdoc.template = 'css2'
-#  rdoc.template = 'doc/jamis.rb'
   rdoc.title    = "Autobuild"
   rdoc.options << '--main' << 'README'
-  rdoc.rdoc_files.include('README', 'CHANGES')
+  rdoc.rdoc_files.include('README', 'CHANGES', 'TODO')
   rdoc.rdoc_files.include('lib/**/*.rb', 'doc/**/*.rdoc')
   rdoc.rdoc_files.exclude('doc/**/*_attrs.rdoc')
 end
@@ -61,11 +57,11 @@ spec = Gem::Specification.new do |s|
   s.name = PKG_NAME
   s.version = PKG_VERSION
   s.summary = 'Rake-based utility to build and install multiple packages with dependencies'
-  s.description = <<EOF
-Autobuild imports, configures, builds and installs various kinds of software packages.
-It can be used in software development to make sure that nothing is broken in the 
-build process of a set of packages, or can be used as an automated installation tool.
-EOF
+  s.description = <<-EOF
+    Autobuild imports, configures, builds and installs various kinds of software packages.
+    It can be used in software development to make sure that nothing is broken in the 
+    build process of a set of packages, or can be used as an automated installation tool.
+  EOF
 
   #### Documentation and testing.
 
@@ -85,7 +81,7 @@ EOF
   #### Advanced project information
   s.platform = Gem::Platform::RUBY
   s.require_paths << "lib"
-  s.add_dependency('rake', '>= 0.6.0')
+  s.add_dependency('rake', '>= 0.7.0')
   s.add_dependency('rmail')
   s.add_dependency('daemons')
   s.files = PKG_FILES.to_a
@@ -125,7 +121,7 @@ task :verify_env_vars do
 end
 
 task :publish_doc do
-  publisher = Rake::RubyForgePublisher.new('xforge', ENV['RUBYFORGE_USER'])
+  publisher = Rake::RubyForgePublisher.new(UNIX_NAME, ENV['RUBYFORGE_USER'])
   publisher.upload
 end
 
@@ -135,7 +131,7 @@ task :release_files => [:gem] do
     "pkg/#{PKG_FILE_NAME}.gem"
   ]
 
-  Rake::XForge::Release.new(MetaProject::Project::XForge::RubyForge.new('xforge')) do |release|
+  Rake::XForge::Release.new(MetaProject::Project::XForge::RubyForge.new(UNIX_NAME)) do |release|
     # Never hardcode user name and password in the Rakefile!
     release.user_name = ENV['RUBYFORGE_USER']
     release.password = ENV['RUBYFORGE_PASSWORD']
@@ -151,7 +147,7 @@ task :publish_news => [:gem] do
     "pkg/#{PKG_FILE_NAME}.gem"
   ]
 
-  Rake::XForge::NewsPublisher.new(MetaProject::Project::XForge::RubyForge.new('xforge')) do |news|
+  Rake::XForge::NewsPublisher.new(MetaProject::Project::XForge::RubyForge.new(UNIX_NAME)) do |news|
     # Never hardcode user name and password in the Rakefile!
     news.user_name = ENV['RUBYFORGE_USER']
     news.password = ENV['RUBYFORGE_PASSWORD']
@@ -160,10 +156,9 @@ end
 
 desc "Tag all the svn files with the latest release number (REL=x.y.z)"
 task :tag do
-  reltag = "RELEASE_#{PKG_VERSION.gsub(/\./, '_')}"
-  puts "Tagging svn with [#{reltag}]"
+  puts "Tagging release"
   base_url = %{svn+ssh://#{RUBYFORGE_USER}@rubyforge.org/var/svn/autobuild}
-  sh %{svn cp #{base_url}/trunk/autobuild #{base_url}/tags/#{reltag}}
+  sh %{svn cp #{base_url}/trunk/autobuild #{base_url}/tags/release/#{PKG_VERSION}}
 end