Smalltalk/X Webserver

Documentation of class 'AbstractSourceCodeManager':

Class: AbstractSourceCodeManager

Inheritance
Description
Class protocol
Private classes

Inheritance:

   Object
   |
   +--AbstractSourceCodeManager
      |
      +--CVSSourceCodeManager
      |
      +--DataBaseSourceCodeManager
      |
      +--FileBasedSourceCodeManager
      |
      +--GitSourceCodeManager
      |
      +--MercurialSourceCodeManager
      |
      +--PerforceSourceCodeManager
      |
      +--StoreSourceCodeManager

Package:: stx:libbasic3

Category:: System-SourceCodeManagement

Version:: rev: 1.429 date: 2024/01/11 10:53:26; user: cg; file: AbstractSourceCodeManager.st directory: libbasic3; module: stx stc-classLibrary: libbasic3

Description:

Abstract superclass for sourceCodeManagers.

Concrete subclasses provide access to a source repository.
Most protocol here traps into subclassResponsbility errors.
Please read more documentation in concrete subclasses 
(especially: CVSSourceCodeManager) for how to use this manager and
what to redefine in another repository manager if required.

Notice (& caveat):
    for very traditional reasons (and because it works for us),
    exept uses CVS for its source code repository,
    and this is best supported in the tools.
    The other managers are provided by third parties and Jan,
    who uses SVN and git.
    You may have to massage those.

copyrightCOPYRIGHT (c) 1995 by Claus Gittinger
             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.

Class protocol:

accessing

availableManagers

return the set of loaded source code managers
(i.e. CVSSourceCodeManager, SVNSourceCodeManager, etc.)

Usage example(s):

     self availableManagers

branchStartTagFor: branchName

this tag is used to tag the original starting point of a branch;
i.e. the head version from which the branch was created.
Here, we use <branchTagPrefix><branchName>_0

branchTagFor: branchName

this tag is used to tag the current branch-head of a branch (or the branch as such);
i.e. the last version checked onto the branch.
Here, we use <branchTagPrefix><branchName>

branchTagPrefix

cacheDirectoryName

return the name of the cache directory, where checked out class
sources are kept for faster access. The default is '/tmp/stx_sourceCache'.
This cache is shared among all ST/X users on a system.

cacheDirectoryName: aStringOrFilename

set the name of the cache directory, where checked out class
sources are kept for faster access. The default is '/tmp/stx_sourceCache'.
This cache is shared among all ST/X users on a system.
The directory is typically set via the launcher's setting menu,
or from a startup rc-file.

cachingSources

return true, if source caching is enabled.
(see cacheDirectoryName for what that means)

cachingSources: aBoolean

enable/disable the caching of source files.
(see cacheDirectoryName for what that means)

Usage example(s):

     AbstractSourceCodeManager cachingSources:true

defaultManager

return the default sourceCodeManager class

enabledManagers

Return list of source code managers that are enabled

Usage example(s):

     self enabledManagers

managerForMatchingModule: aPackageIDMatchString put: aSourceCodeManagerClass

update the per-module manager definitions, adding a manager class for a matchString

managerForPackage: aPackageID

return the sourceCodeManager for a aPackageID, nil if unspecified in the manager per package list

Usage example(s):

     self managerForPackage:'stx:libbasic' 
     self managerForPackage:'stx:libbasic2'
     self managerForPackage:'exept:expecco'

managerPerMatchingModuleDefinitions

return the sourceCodeManager definitions

managerPerMatchingModuleDefinitions: aCollection

set the sourceCodeManager definitions; must be an orderedCollection of packageMatchString -> manager
associations
(not a dictionary, because order is relevant in the matching process, where the first match counts)

named: managerTypeName

AbstractSourceCodeManager named: 'CVS'
AbstractSourceCodeManager named: 'Perforce'

repositoryInfoPerModule

return the dictionary, which associates CVSRoots to module names.
If no entry is contained in this dictionary for some module,
the default cvsRoot (CVSRoot) will be used.

repositoryInfoPerModule: info

ignore here

repositoryName

return the name of the repository.
Since this is an abstract class, return nil (i.e. none)

repositoryNameForPackage: packageId

Return the repository URL for the given package.
Used for testing/debugging source code management configuration

** This method must be redefined in concrete classes (subclassResponsibility) **

shownInBrowserMenus

can be redefined in subclasses which can be suppressed in the browser's menus

shownInBrowserMenus: aBoolean

can be redefined in subclasses which can be suppressed in the browser's menus

useWorkTree

return the setting of useWorkTree, which (eventually)
controls if an up-to-date view of a CVS working tree should be
kept in sync. This is not yet implemented.

useWorkTree: aBoolean

enable/disable the useWorkTree feature, which (eventually)
controls if an up-to-date view of a CVS working tree should be
kept in sync. This is not yet implemented.

utilities

Returns a 'utilities' object that can be used by tools.

By default, it returns an instance of
SourceCodeManagerUtilities with receiver as its
manager, but individual managers may override this
method and supply its own, customized utilities.

Usage example(s):

     SourceCodeManager defaultManager
     SourceCodeManager defaultManager utilities
     CVSSourceCodeManager utilities

workTreeDirectoryName

return the name of the workTree, which is kept in sync
with the current class versions. This is not yet implemented

workTreeDirectoryName: aStringOrFilename

set the name of the workTree, which is kept in sync
with the current class versions. This is not yet implemented

basic access

checkinClass: aClass fileName: classFileName directory: packageDir module: moduleDir source: sourceFile logMessage: logMessage force: force: checkin of a class into the source repository.
Return true if ok, false if not.

** This method must be redefined in concrete classes (subclassResponsibility) **
checkoutModule: aModule directory: aPackage andDo: aBlock: check out everything from a package into a temporary directory.
Then evaluate aBlock, passing the name of that temp-directory.
Afterwards, the tempDir is removed.
Return true, if OK, false if any error occurred.

** This method must be redefined in concrete classes (subclassResponsibility) **
streamForClass: aClass fileName: classFileName revision: revision directory: packageDir module: moduleDir cache: doCache: extract a classes source code and return an open readStream on it.
A revision of nil selects the current (in image) revision.
The classes source code is extracted using the revision and the sourceCodeInfo,
which itself is extracted from the classes packageString.

** This method must be redefined in concrete classes (subclassResponsibility) **
streamForExtensionFile: fileName package: package directory: dir module: mod cache: doCache: check for umlaut-remover/adder bug from felix in extensionsRevisionString !!!!

basic administration

checkForExistingContainer: fileName inModule: moduleName directory: packageDirName: check for a container to be present. Return a boolean result.

** This method must be redefined in concrete classes (subclassResponsibility) **
checkForExistingContainer: fileName inModule: moduleName directory: packageDirName warn: doWarn: check for a container to be present. Return a boolean result.
checkForExistingContainer: fileName inPackage: aPackage: check if a source-code container is present in a packages directory.
checkForExistingContainerForClass: aClass: check if a source-code container for a given class is present in the repository.
checkForExistingModule: moduleName: check for a module directory to be present

** This method must be redefined in concrete classes (subclassResponsibility) **
checkForExistingModule: moduleDir directory: packageDir: check for a package directory to be present

** This method must be redefined in concrete classes (subclassResponsibility) **
createContainerFor: aClass inModule: moduleName directory: dirName container: fileName: create a new container & check into it an initial version of aClass

** This method must be redefined in concrete classes (subclassResponsibility) **
createContainerFor: cls inModule: moduleName package: packageDir container: classFileName: create a new container & check into it an initial version of aClass
createModule: moduleName: create a new module directory

** This method must be redefined in concrete classes (subclassResponsibility) **
createModule: module directory: directory: create a new package directory

** This method must be redefined in concrete classes (subclassResponsibility) **
initialRevisionStringFor: aClass inModule: moduleDir directory: packageDir container: fileName: return a string usable as initial revision string

** This method must be redefined in concrete classes (subclassResponsibility) **
revisionLogOf: clsOrNil fromRevision: firstRev toRevision: lastRef fileName: classFileName directory: packageDirOrNil module: moduleDir
revisionLogOf: clsOrNil fromRevision: rev1OrNil toRevision: rev2OrNil numberOfRevisions: limitOrNil fileName: classFileName directory: packageDirOrNil module: moduleDirOrNil: Return info about the repository container and (part of) the revisionlog as a collection
of revision entries. Return nil on failure.

This must be implemented by a concrete source-code manager

If numRevisionsOrNil is notNil, it limits the number of revision records returned -
only numRevions of the newest revision infos will be collected.

The returned information is a structure (IdentityDictionary)
filled with:
#container -> the container file name (for container-based SCMs)
#cvsRoot -> the CVS root (repository)
#filename -> the actual source file name
#newestRevision -> the revisionString of the newest revision
#numberOfRevisions -> the number of revisions in the container (nil for all)
#revisions -> collection of per-revision info (see below)

firstRevOrNil / lastRevOrNil specify from which revisions a logEntry is wanted:
-If firstRevOrNil is nil, the first revision is the initial revision
otherwise, the log starts with that revision.
-If lastRevOrNil is nil, the last revision is the newest revision
otherwise, the log ends with that revision.

-If both are nil, all logEntries are extracted.
-If both are 0 (not nil), no logEntries are extracted (i.e. only the header).

per revision info consists of one record per revision:

#revision -> the revision string
#author -> who checked that revision into the repository
#date -> when was it checked in
#state -> the RCS state
#numberOfChangedLines -> the number of changed line w.r.t the previous
#logMessage -> the checkIn log message

revisions are ordered newest first
(i.e. the last entry is for the initial revision; the first for the most recent one)
Attention: if state = 'dead' that revision is no longer valid.

** This method must be redefined in concrete classes (subclassResponsibility) **

cache administration

condenseSourceCache

remove all cached old versions (i.e. leave the newest only)

Usage example(s):

     self condenseSourceCache

flushSourceCache

remove all cached versions

Usage example(s):

     self flushSourceCache

change & update

update: something with: aParameter from: changedObject: flush resources on language changes

debugging

verboseSourceCodeAccess
verboseSourceCodeAccess: aBoolean

initialization

forgetDisabledModules

intentionally left blank

initCacheDirPath

initialize the name of the cacheDirectory.
This is:
<tempDir>/stx_sourceCache (non-UNIX)
~/.smalltalk/source-cache (UNIX, as <tempDir> is pruned upon each reboot)

Usage example(s):

     self initCacheDirPath

initialize

setup for caching and no workTree

validateCacheDirPath

obsolete backward compatibility

checkForExistingModule: moduleDir package: packageDir: check for a package directory to be present

** This is an obsolete interface - do not use it (it may vanish in future versions) **
checkoutModule: aModule package: aPackage andDo: aBlock: check out everything from a package into a temporary directory.
Then evaluate aBlock, passing the name of that temp-directory.
Afterwards, the tempDir is removed.
Return true, if OK, false if any error occurred.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
createModule: module package: package: create a new package directory

** This is an obsolete interface - do not use it (it may vanish in future versions) **
getExistingContainersInModule: aModule package: aPackage: return a collection containing the names of existing containers

** This is an obsolete interface - do not use it (it may vanish in future versions) **
getExistingPackagesInModule: aModule: return a collection containing the names of existing packages

** This is an obsolete interface - do not use it (it may vanish in future versions) **
initialRevisionStringFor: aClass inModule: moduleDir package: packageDir container: fileName: return a string usable as initial revision string

** This is an obsolete interface - do not use it (it may vanish in future versions) **

private

checkMethodPackagesOf: aClass

check if aClass contains methods from another package;
ask if these should be checked in with the class.
Raises abortSignal if checkIn is to be suppressed.
returns:
#base - only check in methods from the classes package
#all - check in all

the old code looked for all extensions, and allowed them to be moved to the base-package.
This was dangerous, as if one presses yes too quickly, extensions move to the base too easy.
The new code only allows for extensions from the __NOPROJECT__ package to be moved.
Extensions always remain extensions, and must be moved by an explicit method-menu action.

checkTabSpaceConventionIn: aStream

This method checks whether data in given stream follows
tab-space discipline.

More precisely, this checks that each line starts with zero or more
tabs (16r9) followed by 0-7 spaces (16r32) followed by non-space non-tab
character.
This is done for two reasons:
1) Makefiles (and Make.proto/Make.spec) files MUST not have leading spaces in their rules, but tabs.
otherwise, make fails badly.

2) for diff-comparison, a consisten tab/space discipline avoids false diff-positivies, which resulted from simple
edititing with different editors with different tab conventions.

compileVersionMethod: methodName of: aClass for: newRevisionString

self assert: language isSmalltalk.

containerFromSourceInfo: info

given a sourceInfo, return the classes container

createTempDirectory: packageDir forModule: moduleDir in: aParentDir

create a temp directory for checking out

Usage example(s):

self createTempDirectory:'fooPackage' forModule:'fooModule'

directoryFromContainerPath: containerPath forClass: aClass

given a full path as in an RCS header,
extract the directory (i.e. package).

Usage example(s):

     CVSSourceCodeManager directoryFromContainerPath:'/files/CVS/stx/libbasic/Array.st' forClass:Array

directoryFromContainerPath: containerPath forPackage: packageID

given a full path as in an RCS header,
extract the directory (i.e. package) within the module.
Notice:
for top-level folder-only modules (like exept, stx),
an empty string is returned.

Usage example(s):

     CVSSourceCodeManager directoryFromContainerPath:'/files/CVS/stx/libbasic/Array.st' forPackage:'stx'                 => 'libbasic'
     CVSSourceCodeManager directoryFromContainerPath:'/files/CVS/stx/goodies/refactoryBrowser/Array.st' forPackage:'stx' => 'goodies/refactoryBrowser'
     CVSSourceCodeManager directoryFromContainerPath:'CVS/stx/libbasic/Array.st' forPackage:'stx'                        => 'libbasic'

directoryFromSourceInfo: info

given a sourceInfo, return the classes package directory

isPackageWithoutExtensionMethodConfirmation: aPackageID

usually, the checkin dialog asks if unpackaged methods should be moved
to the package.
This can be suppressed on a per-package base with a checkbox ('do not...again')
in the dialog.
This method returns true, if this was done for a particular package

moduleFromContainerPath: containerPath forClass: aClass

given a full path as in an RCS header, extract the module.

Usage example(s):

     SourceCodeManager moduleFromContainerPath:'/files/CVS/stx/libbasic/Array.st' forClass:Array

moduleFromContainerPath: containerPath forPackage: packageID

given a full path as in an RCS header, extract the module.

Usage example(s):

     SourceCodeManager moduleFromContainerPath:'/files/CVS/stx/libbasic/Array.st'

moduleFromSourceInfo: info

given a sourceInfo, return the classes module directory

packageFromSourceInfo: info

given a sourceInfo, return the classes package directory

** This is an obsolete interface - do not use it (it may vanish in future versions) **

pathInRepositoryFrom: containerPath forPackage: packageID

this tries to extract the path within a repository,
given some path as present in an RCS Header string.
Typically, this ought to be that string directly;
however, if the repository directory is accessed via a symbolic link during
ci/co, some systems extract different strings with co.
One such system here had a symbolic link from /phys/ibm/CVS... to /file/CVS,
and extracted sources had /phys/ibm/CVS in their header.
Do not depend on the code below to work correctly all the time.

Usage example(s):

     SourceCodeManager pathInRepositoryFrom:'/files/CVS/stx/libbasic/Array.st'    forPackage:Array package 
     SourceCodeManager pathInRepositoryFrom:'/phys/ibm/CVS/stx/libbasic/Array.st' forPackage:Array package 

     SourceCodeManager pathInRepositoryFrom:'/files/CVS/stx/libbasic/Array.st'    forPackage:nil          
     SourceCodeManager pathInRepositoryFrom:'/phys/ibm/CVS/stx/libbasic/Array.st' forPackage:nil

postCheckInClass: aClass

invoked after a checkIn

postCheckInExtensionsForPackage: aPackageId

invoked after a checkIn

rememberPackageWithoutExtensionMethodConfirmation: aPackageID

reportError: msg

repositoryTopDirectory

return the name of the repository

sourceCacheDirectory

return the sourceCache directories name.
Ensure that it exists.

sourceInfoOfClass: aClass

helper: return a classes sourceCodeInfo by extracting its
versionString components.

Usage example(s):

     SourceCodeManager sourceInfoOfClass:Array

updateVersionMethod: selector of: aClass for: newRevisionString

helper for the checkin procedure.
Update my #version_XXX method, to now return newRevisionString.

updateVersionMethodOf: aClass for: newRevisionString

helper for the checkin procedure.
Update my #version_XXX method, to now return newRevisionString.

queries

enabled

JV@2012-01-19: Quick hack, see senders. Is that what you mean?

initialRevisionString

redefinable in subclasses

isAbstract

Return if this class is an abstract class.
True is returned here for myself only; false for subclasses.
Abstract subclasses must redefine this again.

isContainerBased

true, if the SCM uses some kind of source container (,v files).
False, if it is like a database or filesystem.

isExperimental

isExtensionsVersionMethodSelector: selector

true if the given selector is for ANY of the manager's extensions version methods.
These are all named extensionVersion_XXX, where XXX is manager-specific (CVS, P4, SVN etc.).
For backward compatibility (times, when there was only one CVS sourcecode manager,
the selector named 'extensionsVersion' alone also counts as a version method
(which might be a somewhat bad idea in the long term...).

isResponsibleForModule: module

isResponsibleForPackage: aStringOrSymbol

Returns true if the manager can handle source code for given package.

Answering true does not imply that receiver is configured default
manager for that package, it only means that it has a repository
configured for given package.

** This method must be redefined in concrete classes (subclassResponsibility) **

isRevision: revision1 after: revision2

true, if the dotted revision string revision1 is > than revision2

Usage example(s):

     SourceCodeManager isRevision:'1' after:'2'      
     SourceCodeManager isRevision:'2' after:'1'      
     SourceCodeManager isRevision:'1.1' after:'2.1.2' 
     SourceCodeManager isRevision:'2.1' after:'1.2.3' 
     SourceCodeManager isRevision:'1' after:'1.1'    
     SourceCodeManager isRevision:'1.1' after:'1'    
     SourceCodeManager isRevision:'1.1' after:'1.2' 
     SourceCodeManager isRevision:'1.10' after:'1.2' 
     SourceCodeManager isRevision:'1.2' after:'1.1' 
     SourceCodeManager isRevision:'1.2.3.4' after:'1.2.3.5' 
     SourceCodeManager isRevision:'1.2.3.4' after:'1.2.3.3' 
     SourceCodeManager isRevision:'1.2.3.4' after:'1.2.3'   
     SourceCodeManager isRevision:'1.2.3.4' after:'1.2.3.4'

isRevision: revision1 sameOrAfter: revision2

true, if the dotted revision string revision1 is >= than revision2

isVersionMethodForExtensionsSelector: selector

true if the given selector is for one of the manager's extensions version methods.
These are all named extensionVersion_XXX, where XXX is manager-specific (CVS, P4, SVN etc.).
For backward compatibility (times, when there was only one CVS sourcecode manager,
the selector named 'extensionsVersion' alone also counts as a version method
(which might be a somewhat bad idea in the long term...).

** This is an obsolete interface - do not use it (it may vanish in future versions) **

isVersionMethodSelector: selector

true if the given selector is for one of the manager's version methods.
These are all named version_XXX, where XXX is manager-specific (CVS, P4, SVN etc.).
For backward compatibility (times, when there was only one CVS sourcecode manager,
the selector named 'version' alone also counts as a version method
(which might be a somewhat bad idea in the long term...).

managerTypeName

Answers version manager name suitable for UI,
i,e., CVS, SubVersion, Perforce

** This method must be redefined in concrete classes (subclassResponsibility) **

managerTypeNameShort

Answers short version manager name suitable for UI,
i,e., CVS, SVN, P4. Used in cases where sorter strings
are preferred. Defaults to #managerTypeName

nameOfVersionMethodForExtensions

that is the old name; now, we use extensionsVersion_<SCM>

nameOfVersionMethodInClasses

that is the old name; now, we use version_<SCM>

performsCompilabilityChecks

Should return true, if the manager itself performs
compilability checks, false otherwise.

Basically a hack, see my senders...

prefixOfVersionMethodForExtensionsSelector

all scm-extensionsVersion methods start with this prefix

prefixOfVersionMethodSelector

all scm-version methods start with this prefix

repositoryTopDirectoryFromSCMRoot

return the top of the repository.

** This method must be redefined in concrete classes (subclassResponsibility) **

revisionAfter: aRevisionString

generate the next revision number after the given number

Usage example(s):

     SourceCodeManager revisionAfter:'1.2.3.4' 
     SourceCodeManager revisionAfter:'123'  
     SourceCodeManager revisionAfter:'1.24'

settingsApplicationClass

link to my settings application (needed for the settings dialog

** This method must be redefined in concrete classes (subclassResponsibility) **

sourceCodeManagerForPackage: aPackageID

JV@2012-01-23: If source code management is disabled, return #().

Usage example(s):

     self sourceCodeManagerForPackage:'stx:libbasic'.
     self sourceCodeManagerForPackage:'stx:libboss'.
     self managerForMatchingModule:'stx:libba*' put:SVNSourceCodeManager.
     self sourceCodeManagerForPackage:'stx:libbasic'.
     self sourceCodeManagerForPackage:'stx:libboss'.

supportsCheckinLogMessages

true, if log-messages are supported

versionInfoClass

versionMethodKeyword

Answers the keyword used by the version management system to
expand a current version in a file (_without_ dollars). For
CVS it is 'Header', for SVN 'Id', others may use different
keywords. If nil is returned, then the version management does
not use any keyword.

versionMethodTemplateForJavaScript

CVSSourceCodeManager versionMethodTemplateForJavaScript

versionMethodTemplateForJavaScriptFor: aSelector

do not make the thing below a single string - otherwise
it would get expanded by the sourcecodemanager, which we do not want here

versionMethodTemplateForRuby

CVSSourceCodeManager versionMethodTemplateForRuby

versionMethodTemplateForRubyFor: aSelector

do not make the thing below a single string - otherwise
it would get expanded by the sourcecodemanager, which we do not want here

versionMethodTemplateForSmalltalk

CVSSourceCodeManager versionMethodTemplateForSmalltalk

versionMethodTemplateForSmalltalkFor: aSelector

do not make the thing below a single string - otherwise
it would get expanded by the sourcecodemanager, which we do not want here

versionString: stringA isLessThan: stringB

source code access

basicCheckinClass: aClass fileName: classFileName directory: packageDir module: moduleDir logMessage: logMessage force: force

low level checkin of a class into the source repository. Does not deal with any version method updates,
only does the checkin, using a temporary file.
Return true if ok, false if not.

checkin: containerFilename text: someText directory: packageDir module: moduleName logMessage: logMessage force: force

enter some (source) code (which is someText)
into the source repository. If the force argument is true, no merge is done;
instead, the code is checked in as given (Dangerous).
Return true if ok, false if not.

checkin: containerFilename text: someText directory: packageDir module: moduleName logMessage: logMessage force: force onBranch: branchNameOrNil

checkinClass: aClass fileName: classFileName directory: packageDir module: moduleDir logMessage: logMessage