"

 COPYRIGHT (c) 2006 by eXept Software AG

              All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

"{ Package: 'stx:libbasic' }"

"{ NameSpace: Smalltalk }"

Object subclass:#ProjectDefinition

	instanceVariableNames:''

	classVariableNames:'LibraryType GUIApplicationType NonGUIApplicationType

		PackagesBeingLoaded Verbose AbbrevDictionary AccessLock

		FolderForSubApplicationsType'

	poolDictionaries:''

	category:'System-Support-Projects'

!

ProjectDefinition class instanceVariableNames:'safeForOverwrittenMethods extensionOverwriteInfo projectIsLoaded'

"

 No other class instance variables are inherited by this class.

"

!

Object subclass:#AbbrevEntry

	instanceVariableNames:'className fileName category numClassInstVars'

	classVariableNames:''

	poolDictionaries:''

	privateIn:ProjectDefinition

!

!ProjectDefinition class methodsFor:'documentation'!

buildingMakefiles

"

    You can define additional rules and flag settings for use in the makeFile generation:

    redefinable build-file attributes:

        stcOptimizationOptions  -> STCLOCALOPT

        stcWarningOptions       -> STCLOCALOPT

        localIncludes_unix      -> LOCALINCLUDES (Make.proto)

        localIncludes_win32     -> LOCALINCLUDES (bc.mak)

    for applications:

        startupClassName

        startupSelector

    for libraries:

"

!

copyright

"

 COPYRIGHT (c) 2006 by eXept Software AG

              All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

!

documentation

"

    As ST/X is (still) very tightly bound with stc, we keep the package and project information

    in a class-object (instead of some project object) and all queries about package contents and 

    attributes are implemented as class methods. 

    This has the advantage, that it can be compiled and included in a compiled class library just like any other class.

    Every package includes a subclass of me (an instance of my meta), which provides useful

    information about the versioning and packaging. 

    Me myself, I know how to generate dependency information and can generate makefiles and other build-support 

    files for compilation (see the browser's 'Checkin Build Support File' menu item. For more details, see

    section 'Build Support Files' below.

    When a package is loaded from a binary shared class lib (i.e. a compiled class library is loaded

    via 'Smalltalk loadPackage:'), the loading is done in multiple phases:

        1) the shared object is loaded, but not installed (registered) in Smalltalk

        2) the ProjectDefinition class is registered and initialized.

        3) the ProjectDefinition class is asked to load its prerequisites. This may lead to other packages

           to be loaded - either as binary class libraries or from source, whichever is found.

        4) the remaining classes and extensions are registered

    ## Some special notes about extension methods:

      if a package is loaded (Smalltalk loadPackage:'foo:bar/baz'), any already loaded package of which

      methods are overwritten by an extension method of the loaded package, the other package is asked to safe those

      methods in its safe(ForOverwrittenMethods). 

      Thus, if the other package or any of its classes is asked

      to file itself out, it can do so using the safe (otherwise, you'd not be able to check the original class into

      its repository while it has an overriding extension loaded).

      Also, the information about which other package was in charge when a method is overwritten is recorded in

      extensionOverwriteInfo. 

      This is used to correctly reinstall an overwritten method, whenever a package is unloaded.

    ## Custom project definition methods

    Some packages may want to compile custom methods when project definition is updated

    based on project contents - similarly to how #classNamesAndAttributes or #extensionMethodNames

    are updated.

    To support this, packages mey add extension methods annotated by <method:category:overwrite:>

    or <method:category:>. The meaning og arguments is the following:

    * method: <Symbol>     - the selector of method which this method generates.

    * category: <Symbol>   - the category in which to place generated method

    * overwrite: <Boolean> - specifies whether the method should obe overwritten

                             or not. Use `false` only for methods which should be

                             generated once and then left for user to manually tweak.

                             optional, defaults to `true` (i.e., do owerwrite methods)

    The annotated method is invoked to get the code od the method to generate, i.e., it must

    return the source code as String. If it returns nil - no method is generated.

    ## Build Support Files

    To support pre-compilation of a package, ProjectDefinition can generate a set of makefiles and other

    support files to allow that. To see the set of files that should be generated, see #fileNamesToGenerate.

    These files are usually generated and saved to the repository upon a commit - the source code management

    does (should) care for this.

    Packages may add more files to this list by defining an (extension) mehtod in project definition class

    and by annotating the method by <file:overwrite:> annotation:

        * the first parameter is the file name to generate as String, relative to the package root. As directory

          separator, use slash (as on UNIX), it will be automagically converted to platform's separator.

        * The second paramterer (true or false) tells the SCM whether the file should be generated (and thus

          overwritten) upon each commit (when true) or only the first time (when false). Important: see the 

          emark below.

        * The method itself should return file's contents a string. If it returns nil, then the file is *not*

          generated at all.

    For examples, see #generate_java_build_auto_dot_xml and #generate_java_build_dot_xml defined by STX:LIBJAVA.

    REMARK: CAUTION:

    The overwrite: boolean is currently *not* supported by old SCM managers, more specifically

    CVSSourceCodeManager does not support it. CVSSourceCodeManager will always overwrite the file!!

    It *is* supported by all SCMs based on new stx:libscm. More specifically, *it is supported* by

    Mercurial.

    ## Adding additional rules to generated makefiles

    There are two ways to add additional rules to generatec makefiles (Make.proto and bc.mak):

      1) overriding #additionalRules_make_dot_proto and/or #additionalRules_bc_dot_mak

      2) addng a method annotated by <file:target:> or <file:target:extends:> 

    ### Overriding #additionalRules* methods

    You may override #additionalRules_make_dot_proto and/or #additionalRules_bc_dot_mak and return

    string containing the code of the rules. This string is inserted to the resulting makefile

    as-is. This is the traditional way of doing this.

    If you any of the targets defined there to be called as part of standard build, you may

    also want to list these targets in #additionalTargets_make_dot_proto and/or

    #additionalTargets_bc_dot_mak

    ### Adding annotatated method

    Alternatively, you may add one method per rule and annotate it by

    <file:target:> or <file:target:extends:> annotation. For example,

    to call ant whenever a package is built, add a method like:

    additionalRuleAnt_make_dot_proto

        <file: 'Make.proto' target: 'ant' extends: 'pre_objs' >  

        ^ '

        java:

                ant -f java/build.xml

        '

    The meaning annotation parameters is the following:

        * file: <String> - name of the file in which to include

          the rule. Currently only two values are valid:

          'Make.proto' and 'bc.mak'.

        * target: <String> - name of the target'

        * extends: <String> - optional name of the target that this additional

          rule extends. This means that the extending target (specified by target:

          annotation parameter) is called as part of building of  the extended target

          (i.e., the target specified by extends: annotation parameter). Not all targets

          are extendable, see below.

    Method annotated by these annotations should return - when executed - a string

    with exactly one rule. The rule name SHOULD match with the name in target: annotation

    parameter, otherwise the extends: parameter will not work correctly.

    If the methor returns nil, the rule is not included in resulting makefile.

    The advantage of this approach is that it allows for additional, non-basic packages to hook in

    and add their own targets if they want to. The disadvantage is that if package makefiles

    are regenerated without this extending package loaded, targets are lost. To avid this,

    you may want to add this non-basic package to prerequsites.

    Currently, this mechanism is used by STX:LIBJAVA to call ant to compile package's java classes.

    #### Extendable targets

    Make.proto:

        all

        clean

        ...more to be added...

    bc.mak

        ALL

        clean

        ...more to be added...

"

! !

!ProjectDefinition class methodsFor:'instance creation'!

definitionClassForPackage:aPackageID

    "given a packageID (such as 'stx:libfoo/bar'), lookup the corresponding peoject definition class.

     Return it, or nil if not present"

    ^ self definitionClassForPackage:aPackageID createIfAbsent:false

    "

     ProjectDefinition definitionClassForPackage:'stx:libbasic'

     ProjectDefinition definitionClassForPackage:'stx:libfoobarBaz'

    "

    "Modified: / 17-08-2006 / 14:33:35 / cg"

!

definitionClassForPackage:aPackageID createIfAbsent:doCreateIfAbsent

    ^ self definitionClassForPackage:aPackageID createIfAbsent:doCreateIfAbsent projectType:nil

    "Modified: / 23-08-2006 / 14:29:15 / cg"

!

definitionClassForPackage: aPackageID createIfAbsent: doCreateIfAbsent projectType:typeOrNil

    |packageDefinitionClassName class|

    packageDefinitionClassName := self projectDefinitionClassNameForDefinitionOf:aPackageID.

    class := Smalltalk classNamed:packageDefinitionClassName.

    class isNil ifTrue:[

        doCreateIfAbsent ifTrue:[

            typeOrNil = GUIApplicationType ifTrue:[

                class := ApplicationDefinition newForPackage:aPackageID.

            ] ifFalse:[

                typeOrNil = NonGUIApplicationType ifTrue:[

                    class := ApplicationDefinition newForPackage:aPackageID.

                ] ifFalse:[

                    typeOrNil = FolderForSubApplicationsType ifTrue:[

                        class := FolderForProjectsDefinition newForPackage:aPackageID.

                    ] ifFalse:[

                        class := LibraryDefinition newForPackage:aPackageID.

                    ]

                ]

            ].

            "setup before prerequisites are defined"

            class setupForType:typeOrNil.

            "/ look what is there and include it; is this ok ?

            class compileDescriptionMethods

        ].

    ] ifFalse:[

        typeOrNil notNil ifTrue:[

            doCreateIfAbsent ifTrue:[

                class projectType == typeOrNil ifFalse: [

                    class setupForType:typeOrNil.

                ]

            ].

        ].

    ].

    ^ class

    "Created: / 23-08-2006 / 14:29:21 / cg"

    "Modified: / 23-08-2006 / 15:35:26 / cg"

!

definitionClassForPackage:newProjectID projectType:typeOrNil createIfAbsent:createIfAbsent

    ^ (self definitionClassForType:typeOrNil)

            definitionClassForPackage:newProjectID

            createIfAbsent:createIfAbsent

            projectType:typeOrNil

    "Created: / 23-08-2006 / 14:28:53 / cg"

!

definitionClassForType: type

    "answer the class that describes a give project type"

    (type = LibraryType) ifTrue:[ ^ LibraryDefinition ].

    (type = GUIApplicationType) ifTrue:[ ^ ApplicationDefinition ].

    (type = NonGUIApplicationType) ifTrue:[ ^ ApplicationDefinition ].

    (type = FolderForSubApplicationsType) ifTrue:[ ^ FolderForProjectsDefinition ].

    (type = 'Application') ifTrue:[ ^ ApplicationDefinition ].     "/ temporary - for backward compat.

    self error:'unknown project type'.

    "Created: / 17-08-2006 / 14:46:28 / cg"

    "Modified: / 23-08-2006 / 13:49:27 / cg"

!

newForPackage:packageID

    ^ self

        newNamed:(self projectDefinitionClassNameForDefinitionOf:packageID)

        package:packageID.

    "Created: / 11-08-2006 / 14:27:19 / cg"

!

newNamed:newName package:packageID

    |newClass|

    "/ for now, we are strict.

    self assert:(self projectDefinitionClassNameForDefinitionOf:packageID) = newName.

    self assert:(self ~~ ProjectDefinition).  "ProjectDefinition is abstract"

    newClass := self

                    subclass:(newName asSymbol)

                    instanceVariableNames:''

                    classVariableNames:''

                    poolDictionaries:''

                    category:(self defaultCategory).

    newClass package:packageID asSymbol.

    ^ newClass

    "Created: / 09-08-2006 / 17:57:37 / fm"

    "Modified: / 09-08-2006 / 19:27:53 / fm"

    "Modified: / 17-08-2006 / 17:24:23 / cg"

! !

!ProjectDefinition class methodsFor:'accessing'!

directory

    "for packageId compatibility"

    ^ self moduleDirectory

    "

     bosch_dapasx_datenbasis_Definition moduleDirectory

     bosch_dapasx_parameter_system_Definition moduleDirectory

     stx_libbasic3 moduleDirectory

     cg_croquet moduleDirectory

     cg_croquet package asPackageId module

     cg_croquet moduleDirectory

     stx_goodies_xml_vw moduleDirectory

    "

    "Created: / 08-08-2006 / 20:25:39 / fm"

    "Modified: / 18-08-2006 / 12:18:33 / cg"

!

extensionsRevisionInfoForManager:managerOrNil

    "return the revisionInfo object for my extensions for a particular source code manager.

     Return nil, if there is either no manager, or I have no extensions"

    |mgr versionMethod revString|

    (mgr := managerOrNil) isNil ifTrue:[

        mgr := SourceCodeManagerUtilities sourceCodeManagerFor:self.

        mgr isNil ifTrue:[

            ^ nil

        ].

    ].

    versionMethod := mgr nameOfVersionMethodForExtensions.

    (self class implements:versionMethod) ifFalse:[^ nil].

    revString := self perform:(mgr nameOfVersionMethodForExtensions) ifNotUnderstood:nil.

    revString isNil ifTrue:[

        ^ nil.

    ].

    ^ mgr revisionInfoFromString:revString.

    "

     (stx_libcomp extensionsRevisionInfoForManager:nil) revision

     (stx_libbasic extensionsRevisionInfoForManager:nil)

    "

    "Created: / 25-11-2011 / 14:34:01 / cg"

!

fullPackageName

    "all components with underlines"

    ^ self fullPackageNameFor: self package

    "

     stx_libwidg2 packageName

     stx_libwidg2 fullPackageName

     stx_goodies_refactoryBrowser_browser packageName

     stx_goodies_refactoryBrowser_browser fullPackageName

    "

!

fullPackageNameFor: aProjectID

    ^ (aProjectID copyReplaceAny:':/' with:$_)

    "

     stx_goodies_refactoryBrowser_lint fullPackageNameFor:#stx_goodies_refactoryBrowser_lint  

    "

!

initialClassNameForDefinitionOf:aPackageId

    <resource: #obsolete>

    "now obsolete - left here for backward compatibility

     given a package-ID, return an appropriate class name for this package"

    ^ self projectDefinitionClassNameForDefinitionOf:aPackageId

    "

     ProjectDefinition projectDefinitionClassNameForDefinitionOf:'bosch:dapasx/interactiver_editor'

     ProjectDefinition projectDefinitionClassNameForDefinitionOf:'stx:libbasic'

     ProjectDefinition projectDefinitionClassNameForDefinitionOf:'stx:goodies/xml'

     ProjectDefinition projectDefinitionClassNameForDefinitionOf:'stx/goodies/xml'

     ProjectDefinition projectDefinitionClassNameForDefinitionOf:'stx_goodies_xml'

    "

!

libraryName

    ^ self package asPackageId libraryName

    "

     bosch_dapasx_datenbasis libraryName

     stx_libbasic3 libraryName

    "

    "Modified: / 09-08-2006 / 18:20:29 / fm"

    "Modified: / 18-08-2006 / 12:36:45 / cg"

!

libraryNameFor:aProjectID

    ^ aProjectID asPackageId libraryName

    "

     bosch_dapasx_datenbasis libraryName

     stx_libbasic3 libraryNameFor:'stx:libbasic'

     stx_libbasic3 libraryNameFor:'bosch:dapasx/datenbasis'

    "

    "Modified: / 09-08-2006 / 18:20:29 / fm"

    "Modified: / 18-08-2006 / 12:37:02 / cg"

!

loadDirectory

    "if I was loaded from a directory (as opposed to loaded via a dll or from a source code manager),

     return that directory. Otherwise return nil."

    ^ self getAttribute:#projectDirectory

!

loadDirectory:aDirectory

    "remember the directory from which I was loaded from"

    self setAttribute:#projectDirectory to:aDirectory

!

module

    ^ self moduleOfClass:self

    "

       bosch_dapasx_datenbasis_Definition module

       DapasX_Datenbasis module

       stx_libbasic3 module

       stx_libbasic3 directory

    "

    "Created: / 08-08-2006 / 20:24:53 / fm"

    "Modified: / 09-08-2006 / 16:16:37 / fm"

    "Modified: / 17-08-2006 / 20:50:46 / cg"

!

moduleDirectory

    ^ (PackageId from:self package) directory

    "

     bosch_dapasx_datenbasis_Definition moduleDirectory

     bosch_dapasx_parameter_system_Definition moduleDirectory

     stx_libbasic3 moduleDirectory

     cg_croquet moduleDirectory

     cg_croquet package asPackageId module

     cg_croquet moduleDirectory

     stx_goodies_xml_vw moduleDirectory

     cg_demos_demo1 moduleDirectory