build/src/tools/stage.jam

#  Copyright (C) Vladimir Prus 2002. Permission to copy, use, modify, sell and
#  distribute this software is granted provided this copyright notice appears in
#  all copies. This software is provided "as is" without express or implied
#  warranty, and with no claim as to its suitability for any purpose.

#  This module defines the 'stage' rule, used to copy a set of targets to
#  a single location
#
#  Typical usage:
#
#  stage dist : hello_world : <location>/usr/bin ;
#
#  The source target will be copied to the specified location. Some targets will
#  we specially processed. In particular, binaries will be relinked. Free properties
#  from stage dist will be included to properties used for relinking. For example
#
#  stage dist : hello_world : <location>/usr/bin <dll-path>/opt/lib ;
# 
#  will cause 'hello_world' to be relinked to the new location, and <dll-path>
#  property will be added when relinking.
#
#  The following properties specifically control 'stage' rule.
# 
#  - <location> tells where to put targets. If not specified, directory
#    with the same name as stage name will be used.
#  
#  - <name> tells the new name of the staged target. In this case, only
#    one target can be specified in sources.
#
#  - <so-version> is Unix specific. It causes all staged libraries to have
#    value of the feature added to the end of name. The libraries will be
#    relinked during staging, so that 'soname' embedded inside the library
#    has the version suffix too.

#  The stage rule can also traverse dependencies, for example to install a
#  program an all required libraries. Two properties affect this.
#
#  - <traverse-dependencies>on tells that dependencies should be traversed.
#    For each target in 'stage' sources, all sources to that target and all
#    dependency properties are traversed. Sources and dependecy properties of
#    those target are traversed recursively.
#
#  - <include-type>SOME_TYPE tells that targets of SOME_TYPE or a type derived
#    from SOME_TYPE, should be included.
#    If no such property is specified, then all found targets will be staged.
#    Otherwise, only targets with types mentioned in <include-type> property
#    will be included.
#    
#    Example usage::
#
#      stage dist : hello_world : 
#        <traverse-dependencies>on <include-type>EXE <include-type>SHARED_LIB ;
#

import targets ;
import "class" : new ;
import property ;
import errors : error ;
import type : type ;
import type ;
import regex ;
import generators ;
import feature ;
import project ;
import property-set ;
import virtual-target ;

feature.feature <traverse-dependencies> : off on : incidental ;
feature.feature <include-type> : : free incidental ;
feature.feature <so-version> : : free incidental ;

class stage-target-class : basic-target
{
    import feature project type errors generators path stage ;    
    import "class" : new ;
    
    rule __init__ ( name-and-dir : project : sources * : requirements * : default-build * )
    {
        basic-target.__init__ $(name-and-dir) : $(project) : $(sources) : $(requirements) 
          : $(default-build) ;
    }

    # If <location> is not set, sets it based on the project data.
    rule update-location ( property-set )
    {
        local loc = [ $(property-set).get <location> ] ;
        if ! $(loc)
        {
            loc = [ path.root $(self.name) [ $(self.project).get location ] ] ;

            property-set = [ $(property-set).add-raw $(loc:G=<location>) ] ;
        }
        
        return $(property-set) ;
    }
        
    # Constructs the targets of types for which a type exists
    # with the form STAGED_*.
    rule construct-special-targets ( name : property-set : source : type )
    {
        local targets = [ generators.construct $(self.project) $(name) : $(type) :
            $(property-set) : $(source) : * ] ;

        return $(targets[2-]) ;
    }
        
    rule construct ( name : source-targets * : property-set )
    {        
        source-targets = [ 
          targets-to-stage $(source-targets) : $(property-set) ] ;
        
        property-set = [ update-location $(property-set) ] ;          
                               
        local result ;
        for local i in $(source-targets)
        {            
            local staged-targets ;
                        
            local properties = [ property-set.empty ] ;
            local a = [ $(i).action ] ;                    
            if $(a)
            {
                properties = [ $(a).properties ] ;
            }
            properties = [ $(properties).add-raw 
              [ $(property-set).free ] ] ;
            
            name = [ targets.tag-name [ $(i).name ] : $(properties) ] ;
                        
            # See if something special should be done when staging this
            # type. It is indicated by presense of special "staged" type            
            local t = [ $(i).type ] ;            
            if $(t) && [ type.registered STAGED_$(t) ]
            {
                staged-targets = [ construct-special-targets $(name) : $(property-set) : $(i) : STAGED_$(t) ] ;
            }
            else             
            {                
                staged-targets = [ stage.copy-file $(name) : $(self.project) : $(i) : $(property-set) ] ;
            }
            
            if ! $(staged-targets)
            {                    
                errors.error "Unable to generate staged version of " [ $(source).str ] ;
            }                
            
            for t in $(staged-targets) 
            {
                result += [ virtual-target.register $(t) ] ;          
            }            
        }
        
        return [ property-set.empty ] $(result) ;
    }   
    

    # Given the list of source targets explicitly passed to 'stage',
    # returns the list of targets which must be staged.
    rule targets-to-stage ( source-targets * : property-set )
    {   
        local result ;
        
        # Traverse the dependencies, if needed.
        if [ $(property-set).get <traverse-dependencies> ] = "on"
        {
            source-targets = [ collect-targets $(source-targets) 
              : [ $(property-set).get <include-type> ] ] ;
        }
        
        # Filter the target types, if needed
        local included-types = [ $(property-set).get <include-type> ] ;               
        if $(included-types)
        {
            for local r in $(source-targets)
            {
                local ty = [ $(r).type ] ;        
                if $(ty) && $(ty) != SEARCHED_LIB
                {
                    if [ include-type $(ty) : $(included-types) ]                  
                    {
                        result += $(r) ;
                    }                
                }           
            }
        }
        else
        {
            # Intermediate targets are those with "unrequested" types.
            # For example, given "exe a : a.cpp" we can end with RSP
            # target on windows, and it will be marked as "intermediate".
            # By default, we don't install such targets.
            # If specific list of installable types is given, we don't
            # care if target is intermediate or not.
            for local r in $(source-targets)
            {                
                if ! [ $(r).intermediate ]
                {
                    result += $(r) ;
                }
            }            
        }
                
        return $(result) ;
    }
    
    rule collect-targets ( targets * : types-to-include * )
    {
        # Find subvariants
        local s ;        
        for local t in $(targets)
        {
            s += [ $(t).creating-subvariant ] ;
        }
        s = [ sequence.unique $(s) ] ;
        
        local result = $(targets) ;
        for local i in $(s)
        {
            result += [ $(i).all-referenced-targets ] ;
        }
        local result2 ;
        for local r in $(result)
        {
            if $(r:G) != <use>
            {
                result2 += $(r:G=) ;
            }            
        }        
        result = [ sequence.unique $(result2) ] ;        
    }
                
    # Returns true iff 'type' is subtype of some element of 'types-to-include'.
    local rule include-type ( type : types-to-include * )
    {
        local found ;
        while $(types-to-include) && ! $(found)
        {
            if [ type.is-subtype $(type) $(types-to-include[1]) ]
            {
                found = true ;
            }            
            types-to-include = $(types-to-include[2-]) ;
        }
        
        return $(found) ;
    }
    
    
}

# Create a target named 'name' in the current project
# which will be created by copying of 'source'
rule copy-file ( name ? : project : source : extra-properties )
{   
    local n = [ $(source).name ] ;
    # Not sure what it does. Tests seem to tolerate removal of
    # this code. 
    if $(name)
    {
        n = $(name) ;
    }
        
    targets = [ new file-target $(n:D=) : [ $(source).type ] 
      : $(project) ] ;
    local a = [ $(source).action ] ;
    local new-a ;
    if $(a)
    {            
        local p = [ $(a).properties ] ;
        # Copy the properties of original target. They, in particular
        # can affect the suffix of the target.
        new-a = [ new action $(targets) : $(source) : common.copy : 
          [ $(p).add-raw [ $(extra-properties).free ] ] ] ;
    }
    else
    {
        new-a = [ new action $(targets) : $(source) : common.copy :
          [ property-set.create [ $(extra-properties).free ] ] ] ;
    }                                
    $(targets).suffix [ $(source).suffix ] ;
    $(targets).action $(new-a) ;
    
    return $(targets) ;
}

rule relink-file ( project : property-set : source ) 
{
    local action = [ $(source).action ] ;
                       
    # stage can affect the relinking details.
    local ps = [ $(action).properties ] ;
    local ps-raw = [ $(ps).raw ] ;
    # Unless <hardcode-dll-paths>true is in properties, which can
    # happen only if the user has explicitly requested it, nuke all
    # <dll-path> properties.
    if [ $(property-set).get <hardcode-dll-paths> ] != true
    {
        ps-raw = [ property.change $(ps-raw) : <dll-path> ] ;
    }
    ps-raw = $(ps-raw) [ $(property-set).free ] ;
    local new-ps = [ property-set.create $(ps-raw) ] ;
    
    local cloned-action = [ virtual-target.clone-action $(action) : $(project) :
      "" : $(new-ps) ] ;
    local result = [ $(cloned-action).targets ] ;                        
    
    return $(result) ;
}




# Declare staged version of the EXE type. Generator for this type will
# cause relinking to the new location.
type.register STAGED_EXE : : EXE ;

class stage-exe-generator : generator
{
    import type property-set modules stage ;
    
    rule __init__ ( )
    {
        generator.__init__ stage-exe : EXE : STAGED_EXE ;
    }
    
    rule run ( project name ? : property-set : source : multiple ? )
    {
        return [ stage.relink-file $(project) : $(property-set) : $(source) ] ;
    }    
}

generators.register [ new stage-exe-generator ] ;

type.register STAGED_SHARED_LIB : : SHARED_LIB ;

class stage-shared-lib-generator : generator
{
    import type property-set modules stage ;    
       
    rule __init__ ( )
    {
        generator.__init__ stage-lib : SHARED_LIB : STAGED_SHARED_LIB ;
    }
    
    rule run ( project name ? : property-set : source : multiple ? )
    {
        local name-changed ;
        if [ $(property-set).get <so-version> ]
        {
            name-changed = true ;
        }
        if $(name) != [ $(source).name ]
        {
            name-changed = true ;
        }
        
        if $(name-changed) && [ modules.peek : UNIX ] 
        {
            # Need to change the name of the target and relink
            local relinked = 
              [ stage.relink-file $(project) : $(property-set) : $(source) ] ;
            # FIXME: use hardcoded .so.
            local so-version = [ $(property-set).get <so-version> ] ;
            $(relinked).suffix so.$(so-version) ;
            # Break into private member of 'virtual-target' and change
            # the name.
            modules.poke $(relinked) : self.name : $(name) ;
            return $(relinked) ;
        }
        else
        {            
            return [ stage.copy-file $(name) : $(project) 
              : $(source) : $(property-set) ] ;
        }        
    }    
}

generators.register [ new stage-shared-lib-generator ] ;




# Declares a stage target. When build, it will construct all sources
# and place in one directory. The directory can be specified in requirements
# with 'location' property. If not specified, the directory name will be
# the same as target name, relative to the project where the target 
# is declared.
rule stage ( name : sources * : requirements * : default-build * )
{
    local project = [ project.current ] ;
    
    # Unless the user has explicitly asked us to hardcode dll paths, add
    # <hardcode-dll-paths>false in requirements, to override default
    # value.
    if ! <hardcode-dll-paths>true in $(requirements)
    {
        requirements += <hardcode-dll-paths>false ;
    }        
   
    targets.main-target-alternative
      [ new stage-target-class $(name) : $(project) 
        : [ targets.main-target-sources $(sources) : $(name) ]
        : [ targets.main-target-requirements $(requirements) : $(project) ] 
        : [ targets.main-target-default-build $(default-build) : $(project) ] 
      ] ;
}

IMPORT $(__name__) : stage : : stage ;