[Boost-build] How to implement an installer target.

From: Jurko Gospodnetiæ (jurko.gospodnetic_at_[hidden])
Date: 2008-05-02 15:06:45

   Hi all

   I need opinions on how to design packaging end-user installers using 
Boost Build.

   Note that I am not interested in details of adding detailed support 
for different installation packaging utilities but only the way to make 
Boost Build actually pass needed file target information on to them.

===========================================
   Suppose the following:
===========================================

     1. We want to construct an installer package that would place:
        - target A in folder F1/F2
        - target B in folder F3.

     2. We have an external tool create-installer() which takes an input 
file containing information about all the files to be placed in the 
installer as well as any other needed information (e.g. installer name, 
version information and whatever else pops to mind) and mangles it all 
up into a single nice installer package.

===========================================
   The problem:
===========================================

   The problem how is constructing this input file containing the 
following information:
   path-to-built-target-A --> F1/F2
   path-to-built-target-B --> F3

===========================================
   Design idea I would like to discuss:
===========================================

--------------
--- Usage: ---
--------------

     installer-source is-A : A : <installer-location>F1/F2 ;
     installer-source is-B : B : <installer-location>F2 ;
     installer my-installer : is-A, is-B ;

-----------------------------------------
--- What would happen under the hood: ---
-----------------------------------------

We would need the following new classes:

   Boost Build target classes:
     installer-target
     installer-source-target

   Boost Build virtual target classes:
     installer-source-virtual-target

installer rule would create an installer-target.

installer-target would:
   - process all the source virtual targets it got
   - prepare the input file for the external create-installer() tool 
(using the same 'response file' technique currently used for 
constructing msvc compiler and linker response files)
   - return a file-target with a hooked action for running the tool.
   - automatically be made explicit since it makes no sense to build
     it except when requested as a source for an installer-target.

   The problem is how to pass all the needed information to this target. 
The only place we can stash this information is in the virtual-target 
sources passed to its construct() rule but virtual-target class allows 
no additional information to be hooked to it.

   That is why we create the installer-source-virtual-target class which 
would contain the information about all the sources in a single group of 
files defined by a single installer-source rule call together with the 
information about where they should be located in the installer. It 
should not actualize to any Jam targets and is used only as a holder for 
this information so it can be processed by installer-target in its 
construct() rule. Also, this construct() rule should then report an 
error in case it receives a source virtual target of type other than 
installer-source-virtual-target.

   Now these installer-source-virtual-target objects need to be created 
from information we pass to the installer-source-target rule. That means 
that this rule needs to create an installer-source-target object which 
would package all this information into installer-source-virtual-target 
objects in its construct() rule.

===========================================
   What I do not like about this design and would like ideas on how to 
circumvent:
===========================================

   1. input files for the external create-installer() tool are created 
not as actual Boost Jam targets but directly from Boost Build rules. 
This means that they can not be cleaned/tracked using Boost Build.

   2. It is possible to request building installer-source-targets 
explicitly even though that will not actually run any actions and will 
create no files.

   3. My gut says it should be simpler than this. This requires defining 
2 custom target classes and a custom virtual target class and I am not 
sure those classes actually model is what they are supposed to be modeling.

===========================================
   What we have actually implemented:
===========================================

   We implemented a similar system by using install rules to stage the 
files in the format they will be stored in in the installer in a 
specific folder on the disk and then constructed the installer from there.

   This solution works but requires extra copying into the temporary
staging folder and we currently found no way to make this temporary 
folder be constructed based on the given build's property-set so 
building multiple such installers from a single command fails due to 
multiple targets being bound to the same file name.

   The design above is part of some playing around to see if we can 
remove these limitations.

   Any comments would be greatly appreciated.

   Best regards,
    Jurko Gospodnetiæ