#==============================================================================
# jobber.cfg
#
# Copyright (C) 2000-2004 by Eric Sunshine <sunshine@sunshineco.com>
#
# CEL-specific configuration for jobber.pl, a generalized tool for performing
# maintenance tasks on a project's source base and documentation.  The
# configuration file is just normal Perl code.
#
# For CEL, we configure jobber.pl to checkout the CEL source tree from the CVS
# repository and then perform the following tasks, after which it commits any
# changes back to the repository:
#
# * Convert Texinfo documentation to HTML format.
# * Build the public API reference manual.
# * Re-build Visual-C++ DSW/DSP and SLN/VCPROJ project files.
# * Re-build the Swig-generated Python files.
# * Make all generated HTML (manual and API) available online for browsing.
# * Make archives of the generated HTML available for download.
#
#==============================================================================

# Minimum jobber.pl version expected by this configuration.
jobber_require(32);


#==============================================================================
# *** External Client Configuration Section ***
#
# Use this section to configure tools or environment which might impact
# jobber.pl indirectly. For instance, you might augment the PATH environment
# variable or set the CVS_RSH environment variable. At the command-line,
# jobber.pl allows users to define arbitrary run-time properties via the --set
# option. These properties can be accessed by consulting the %jobber_properties
# hash. For instance, the command-line argument "--set foo=bar" sets "bar" as
# the value of $jobber_properties{foo}.
#==============================================================================

#------------------------------------------------------------------------------
# We prefer that the CVS username is specified on the command-line via
# "--set cvsuser=someone".
#------------------------------------------------------------------------------
exists $jobber_properties{'cvsuser'} or
    die "ERROR: You must set the CVS username via `--set cvsuser=someone'\n";
my $cvsuser = $jobber_properties{'cvsuser'};

#------------------------------------------------------------------------------
# Swig generation in CEL relies upon Swig .i files from Crystal Space, which in
# turn rely upon most of the Crystal Space headers. To gain access to these
# files, we extract them from the Crystal Space CVS repository as one of the
# tasks in @jobber_tasks. We also have $configure (below) set
# CRYSTAL.INCLUDE_DIR to point at the extracted headers since the Swig
# generation needs to know the location of these files. As a convenience, we
# extract the CS include directory into jobber's working directory so that it
# will be cleaned up automatically when the script terminates.
#------------------------------------------------------------------------------
my $cs_cvs_root = ":ext:$cvsuser\@cvs.crystalspace3d.org:/cvsroot/crystal";
my $cs_include_dir = "CS/include";
my $cs_checkout = "cvs -Q -z9 -d $cs_cvs_root checkout -P $cs_include_dir";

#------------------------------------------------------------------------------
# The parent location where browseable and downloadable Crystal Space
# documentation is placed. Used in the composition of $jobber_browseable_dir
# and $jobber_package_dir.
#------------------------------------------------------------------------------
my $cel_base_doc_dir = '/home/crystal/www/htdocs/cel/docs';

#------------------------------------------------------------------------------
# SourceForge's shell machine does not have compilers or other build tools
# installed, so we can not invoke CEL's configure script to prepare the
# project.  Instead, we fake up project configuration by manually creating a
# minimal Jamconfig and Jamfile.
#------------------------------------------------------------------------------
my $configure = 
    "celver=`./configure --version | awk '/cel/ { print \$3 }'`\n" .
    "celverlist=`echo \$celver | tr '.' ' '`\n" .
    "celcopy=`sed '/\\[[Cc]opyright/!d;s/[^[]*\\[\\([^]]*\\)\\].*/\\1/'" .
    "  < configure.ac`\n" .
    "cat << EOF > Jamconfig\n" .
    "CMD.C++ ?= \"g++\" ;\n" .
    "CMD.CC ?= \"gcc\" ;\n" .
    "CMD.DOT ?= \"dot\" ;\n" .
    "CMD.DOXYGEN ?= \"doxygen\" ;\n" .
    "CMD.DVIPS ?= \"dvips\" ;\n" .
    "CMD.LINK ?= \"\\\$(CMD.C++)\" ;\n" .
    "CMD.MAKEINFO ?= \"makeinfo\" ;\n" .
    "CMD.MKDIR ?= \"mkdir\" ;\n" .
    "CMD.MKDIRS ?= \"mkdir -p\" ;\n" .
    "CMD.OBJC ?= \"gcc\" ;\n" .
    "CMD.OBJC++ ?= \"g++\" ;\n" .
    "CMD.SWIG ?= \"swig\" ;\n" .
    "CMD.TEXI2DVI ?= \"texi2dvi\" ;\n" .
    "JAM ?= \"jam\" ;\n" .
    "MODE ?= \"optimize\" ;\n" .
    "MSVCGEN_SILENT ?= \"yes\" ;\n" .
    "PACKAGE_COPYRIGHT ?= \"\$celcopy\" ;\n" .
    "PACKAGE_HOMEPAGE ?= \"http://cel.crystalspace3d.org/\" ;\n" .
    "PACKAGE_LONGNAME ?= \"Crystal Entity Layer\" ;\n" .
    "PACKAGE_NAME ?= \"cel\" ;\n" .
    "PACKAGE_STRING ?= \"cel \$celver\" ;\n" .
    "PACKAGE_VERSION ?= \"\$celver\" ;\n" .
    "PACKAGE_VERSION_LIST ?= \$celverlist ;\n" .
    "PERL ?= \"perl\" ;\n" .
    "PYTHON ?= \"python\" ;\n" .
    "PYTHON.AVAILABLE ?= \"yes\" ;\n" .
    "RUN_TTREE ?= \"ttree\" ;\n" .
    "TARGET.OS ?= \"UNIX\" ;\n" .
    "CRYSTAL.INCLUDE_DIR ?= \"$cs_include_dir\" ;\n" .
    "EOF\n" .
    "sed 's/\@top_srcdir\@/./;s/\@top_builddir\@//' < Jamfile.in > Jamfile\n" .
    "mkdir -p include\n" .
    "cat << EOF > include/csconfig.h\n" .
    "#ifndef __CS_CSCONFIG_H__\n" .
    "#define __CS_CSCONFIG_H__\n" .
    "#define CS_HAVE_INTTYPES_H\n" . 
    "#define CS_HAVE_STDINT_H\n" .
    "#endif // __CS_CSCONFIG_H__\n" .
    "EOF\n"
    ;

#------------------------------------------------------------------------------
# For write-access, SourceForge requires SSH access.
#------------------------------------------------------------------------------
$ENV{'CVS_RSH'} = 'ssh';

#------------------------------------------------------------------------------
# Ensure that various tools can be found.
#------------------------------------------------------------------------------
$ENV{'PATH'} .= ':/usr/local/bin';


#==============================================================================
# *** Jobber Configuration Section ***
#==============================================================================

#------------------------------------------------------------------------------
# $jobber_project_root [required]
#     Root directory of the project.  This is the top-level directory created
#     as a side-effect of retrieving the files from CVS. No default.
#------------------------------------------------------------------------------
$jobber_project_root = 'cel';

#------------------------------------------------------------------------------
# $jobber_cvs_root [required]
#     The CVSROOT setting used for invoking CVS commands.  The specified value
#     must allow "write" access to the repository if files are to be committed
#     back to the repository. No default.
#------------------------------------------------------------------------------
$jobber_cvs_root = ":ext:$cvsuser\@cvs.crystalspace3d.org:/cvsroot/cel";

#------------------------------------------------------------------------------
# $jobber_cvs_sources [optional]
#     All directories which need to be extracted from the repository in order
#     to perform the conversion process.  This list should include the
#     documentation directories as well as those containing tools and
#     supporting files needed by the tasks in the $jobber_tasks list.  This
#     list may contain CVS module aliases since it is used with the CVS
#     'checkout' command (i.e. "cvs checkout -P $jobber_cvs_sources").
#     Default: $jobber_project_root
#------------------------------------------------------------------------------
#$jobber_cvs_sources = $jobber_project_root;

#------------------------------------------------------------------------------
# $jobber_cvs_flags [optional]
#     Additional flags to pass to each of the `cvs' command invocations.  An
#     obvious example would be to set this variable to "-z9" to enable
#     compression. No default.
#------------------------------------------------------------------------------
#$jobber_cvs_flags = '-z9';

#------------------------------------------------------------------------------
# $jobber_browseable_dir [conditional]
#     Absolute path of directory into which generated documentation should be
#     copied for online browsing. This setting is required if any tasks publish
#     documentation, otherwise it is optional. No default.
#------------------------------------------------------------------------------
$jobber_browseable_dir = "$cel_base_doc_dir/online";

#------------------------------------------------------------------------------
# $jobber_package_dir [conditional]
#     Absolute path of directory into which archives of generated documentation
#     are placed to make them available for download in package form.  This
#     setting is required if any tasks publish documentation, otherwise it is
#     optional.  No default.
#------------------------------------------------------------------------------
$jobber_package_dir = "$cel_base_doc_dir/download";

#------------------------------------------------------------------------------
# $jobber_public_group [optional]
#     Group name to which to assign ownership of all directories which will
#     exist after script's termination (such as the "browseable" directory).
#     May be 'undef' if no special group should be assigned. Default: undef
#------------------------------------------------------------------------------
$jobber_public_group = 'crystal';

#------------------------------------------------------------------------------
# $jobber_public_mode [optional]
#     Mode to which to assign all directories which will exist after script's
#     termination (such as the "browseable" directory).  Use this in
#     conjunction with $jobber_public_group to make directories group-writable,
#     for example. For this purpose, set it to the octal value 0775.  May be
#     'undef' if no special mode should be assigned. Default: undef
#------------------------------------------------------------------------------
$jobber_public_mode = 0775;

#------------------------------------------------------------------------------
# $jobber_temp_dir [optional]
#     Absolute path of temporary working directory where all processing should
#     occur.  The script cleans up after itself, so nothing will be left in
#     this directory after the script terminates. Default: "/tmp"
#------------------------------------------------------------------------------
#$jobber_temp_dir = '/tmp';

#------------------------------------------------------------------------------
# @jobber_binary_override [optional]
#     Normally, jobber.pl determines automatically whether files which it adds
#     to the repository are binary or text (CVS needs to know this
#     information).  There may be special cases, however, when text files need
#     to be treated as binary files. This setting is a list of regular
#     expressions which are matched against the names of files being added to
#     the CVS repository.  If a filename matches one of these expressions, then
#     it is considered binary (thus, the CVS "-kb" option is used).  An example
#     of when this comes in handy is when dealing with Visual-C++ DSW and DSP
#     project files in which the CRLF line-terminator must be preserved.
#     Default: .dsw and .dsp files
#------------------------------------------------------------------------------
#@jobber_binary_override = ('(?i)\.(dsw|dsp)$');

#------------------------------------------------------------------------------
# @jobber_tasks [required]
#     A list of tasks to perform on the checked-out source tree.  Typical tasks
#     are those which repair outdated files, and those which generate
#     human-consumable documentation from various sources.  Files generated or
#     repaired by the tasks can then optionally be committed back to the CVS
#     repository and/or published for browsing or download. Each task's
#     "command" is invoked in the top-level directory of the project tree
#     ($jobber_project_root).
#
#     Many projects need to be "configured" before various tasks can be
#     performed (often by running some sort of configuration script). If this
#     true for your project, then your very first task should invoke the
#     command(s) which configure the project.
#
#     Each task record is a dictionary which contains the following keys:
#
#     name [required]
#         Human-readable name for this task; used in status messages.
#     action [required]
#         Human-readable verb which describes the action performed by this
#         target. It is combined with the value of the "name" key to construct
#         an informative diagnositc message.
#     command [optional]
#         The actual command which is invoked to perform this task. It may
#         repair outdated files or generate a set of files (such as HTML
#         documentation).
#     newdirs [optional]
#         Refers to an array of directories into which files are generated by
#         this task.  This key should only be present if new files are created
#         by this target.
#     olddirs [optional]
#         Refers to an array of existing directories where files generated by
#         this task are stored in the CVS repository.  If the "newdirs" key is
#         omitted, then the directories mentioned by "olddirs" are those
#         containing files modified in-place by the command, rather than
#         generated anew in a different location.  If both "newdirs" and
#         "olddirs" are present, then entries in "newdirs" must correspond to
#         entries in "olddirs", and each directory in "newdirs" must exactly
#         mirror the layout and hierarchy of each corresponding directory in
#         "olddirs".
#     log [optional]
#         Log message to use for CVS transactions involving this target.  The
#         keys "olddirs" and "log" should be present only if the files
#         generated by this target should be committed back into the CVS
#         repository.
#     export [optional]
#         Refers to a sub-dictionary which describes how to export the target.
#         This key should be present only if the files generated by the task
#         should be published for browsing and downloading.  If this key is
#         used, then one or both of "olddirs" and "newdirs" must also be
#         present.  The sub-dictionary referenced by the "export" entry may
#         contain the following keys:
#
#         dir [required]
#             Directory name into which files for this task are published.
#             Online browseable files are placed into
#             $jobber_browseable_dir/$dir, and downloadable packages are placed
#             into $jobber_package_dir/$dir.
#         name [required]
#             Base package name used when generating downloadable packages via
#             @jobber_archivers (see below).  When published, the base package
#             name is combined with the archiver's file extension and placed
#             within the appropriate subdirectory of $jobber_package_dir.
#             *NOTE* Presently, the implementation is limited to only exporting
#             the first directory referenced by the sibling "newdirs" key.
#         appear [optional]
#             Controls the appearance of the directory in the generated
#             package.  For example, when packaging files from a temporary
#             build directory named "./out/docs/html/manual", it might be
#             preferable if it actually appeared as "CS/docs/html/manual" in
#             the downloadable package.
#         browseable-postprocess [optional]
#             Allows specification of a post-processing step for documentation
#             which is being made available for online browsing.  The value of
#             this key is any valid shell command.  It is invoked after the
#             files have been copied to the browseable directory. If the
#             meta-token ~T appears in the command, then the path of the
#             directory into which the files have been published is
#             interpolated into the command in its place.
#------------------------------------------------------------------------------
@jobber_tasks =
    ({ 'name'    => 'build environment',
       'action'  => 'Configuring',
       'command' => $configure },
     { 'name'    => 'Crystal Space Swig input files',
       'action'  => 'Extracting',
       'command' => $cs_checkout },
     { 'name'    => 'Visual-C++ project files',
       'action'  => 'Repairing',
       'command' => 'jam msvcgen',
       'newdirs' => ['out/msvc'],
       'olddirs' => ['msvc'],
       'log'     => 'Automated Visual-C++ project file repair.' },
     { 'name'    => 'Swig Python files',
       'action'  => 'Repairing',
       'command' => 'jam blcelfreeze',
       'olddirs' => ['plugins/behaviourlayer/python', 'scripts'],
       'log'     => 'Automated Swig Python file repair.' },
     { 'name'    => 'User\'s Manual',
       'action'  => 'Generating',
       'command' => 'jam manualhtml',
       'newdirs' => ['out/docs/html/manual'],
       'olddirs' => ['docs/html/manual'],
       'log'     => 'Automated Texinfo to HTML conversion.',
       'export'  =>
	   { 'dir'    => 'manual',
	     'name'   => 'celmanual-html',
	     'appear' => "$jobber_project_root/docs/html/manual" }},
     { 'name'    => 'Public API Reference',
       'action'  => 'Generating',
       'command' => 'jam apihtml && rm -f out/docs/html/api/*.m??',
       'newdirs' => ['out/docs/html/api'],
       'olddirs' => ['docs/html/api'],
       'log'     => 'Automated API reference generation.',
       'export'  =>
	   { 'dir'    => 'api',
	     'name'   => 'celapi-html',
	     'appear' => "$jobber_project_root/docs/html/api" }},
     );

#------------------------------------------------------------------------------
# @jobber_archivers [optional]
#     A list of archiver records.  An archiver is used to generate a package
#     from an input directory.  Each entry in this list is a dictionary which
#     contains the following keys:
#
#     name [required]
#         Specifies the archiver's printable name.
#     extension [required]
#         File extension for the generated archive file.
#     command [required]
#         Command template which describes how to generate the given archive.
#         The template may contain the meta-token ~S and ~D.  The name of the
#         source directory is interpolated into the command in place of ~S, and
#         the destination package name is interpolated in place of ~D.
#
#     As a convenience, jobber.pl defines several pre-fabricated archiver
#     dictionaries:
#
#     $ARCHIVER_BZIP2
#         Archives with 'tar' and compresses with 'bzip2'. Extension: .tar.bz2
#     $ARCHIVER_GZIP
#         Archives with 'tar' and compresses with 'gzip'. Extension: .tgz
#     $ARCHIVER_ZIP
#         Archives and compresses with 'zip'. Extension: .zip
#
#     Default: ($ARCHIVER_BZIP2, $ARCHIVER_GZIP, $ARCHIVER_ZIP)
#------------------------------------------------------------------------------
# @jobber_archivers = ($ARCHIVER_BZIP2, $ARCHIVER_GZIP, $ARCHIVER_ZIP);
