Mantis - Squeak
Viewing Issue Advanced Details
ID: Category: Severity: Reproducibility: Date Submitted: Last Update:
7562 Documentation minor always 09-08-10 11:00 09-12-10 21:34
Reporter: hirzel Platform:  
Assigned To: casey OS:  
Priority: normal OS Version:  
Status: assigned Product Version:  
Product Build: Resolution: open  
Projection: none      
ETA: none Fixed in Version:  
Summary: 0007562: PackageInfo class comment
Description: The current comment is

"Subclass this class to create new Packages"

There should be an indication how to do this and a note about the options of using or not using it.

There is no instance variable to keep a description of the package.
Steps To Reproduce:
Additional Information: PackageInfo instances are displayed by.

   PackageList open

----------------------------
Squeaklist Wed, Sep 1, 2010 at 1:57 PM
On 01.09.2010, at 10:23, Frank Shearar wrote:

> Andreas' latest commit had me looking at my SIP stack for the first time in a while.
>
> I had named it Network-SIP, because SIP's a network protocol, and I thought of the naming convention as indicating a nested approach.
>
> It seems that I'm mistaken here though - really, categories are a flat space, so classes in Network-SIP show up as part of the Network package.

Well, only if a Network package exists. And if it does not define a custom PackageInfo. If it did, it could exclude "Network-SIP".

> If I now understand correctly then, the mapping between class categories and packages uses the first token of the category name (so the characters before the first '-'). Is that right?

It's just a convention. Most packages in trunk follow that convention. But e.g. ToolBuilder and HelpBrowser do not.

When using the default package info then it depends solely on the name of the package. It matches a category named exactly like the package, plus all categories beginning with the package name and a hyphen. But the package name itself can well contain a hyphen, too.

See class PackageInfo, it's pretty straight-forward.

A package can include or exclude arbitrary classes and methods though, by subclassing PackageInfo. We don't use that in trunk, but third-party packages can, and occasionally do. Seaside used to do that. A particularly ingenious example is HMM's PackageInfo for OMeta2.

> If so then I think I should rename my categories from Network-SIP-Foo to, say, SipStack-Foo, yes? (Like WebClient isn't Network-WWW.)

Despite what I explained above, yes ;) If you care about sort order, NetworkSIP-Foo would work, too.

- Bert -

===================================
Squeaklist Fri, Sep 3, 2010 at 10:08 PM

Bernhard Pieber
<bernhard@pieber.com> Fri, Sep 3, 2010 at 10:08 PM

Am 03.09.2010 um 19:59 schrieb Ralph Johnson:
> On 9/3/10, Bert Freudenberg <bert@freudenbergs.de> wrote:
>> A package is a (sub-) instance of PackageInfo. Packages are held by PackageOrganizer.
>>
>> One idea would be to include a PackageInfo subclass in each package, and its class comment or methods would describe the package. That would hook into HelpSystem so one could browse comments, instructions, examples etc. per package.
>>
>> There are a few conventions for that already, e.g. the class name should end in "Info" and it should be in a category named "PackageName-Info".
> We could certainly include a PackageInfo subclass in a package. But
> Monticello wouldn't use it to make the instance of the package, would
> it?
The strange thing is that PackageInfo supported subclasses from day one. According to Avi they were even required at first. However, I looked but could not find a place in the code where they are instantiated. It seems that one has to manually register them by code in order to use them. It seems that no PackageInfo subclasses can be created by just using the tools. :-/

- Bernhard

=====================================

Andreas Raab does not like the idea of subclassing, Reason?


Squeaklist Sat, Sep 4, 2010 at 2:40 AM

If you explore "PackageOrganizer default packages" in 4.1 you will find that there is (for example) AnObsoleteFlexibleVocabulariesInfo. Which illustrates my dislike of PI subclassing very well :-)
Relationships
Attached Files:

Notes
(0013873)
hirzel   
09-08-10 11:05   
On 04.09.2010, at 07:53, Hannes Hirzel wrote:

> 1) How are the 29 PackageInfo instances currently used?

To gather info about which classes and methods are in a Monticello package. Also, to hold package load/unload scripts (which is a hack).

> How have they been created?

Typically by MCPackage>>packageInfo.

Or interactively. E.g. one can ask for all ToolBuilder classes even though ToolBuilder is 4 separate MC packages in trunk:

       (PackageInfo named: 'ToolBuilder') classes

> 2) What does the PackageOrganizer instance do?

It holds onto PackageInfo instances, so that after creating one you always get the same instance.

> Is it just used by the PackagePaneBrowser?

The PackagePaneBrowser has nothing to do with packages. It operates on class categories, not packages. I do not find it useful.

The only shipping browser showing packages is in Monticello, when you click "browse". Monticello has a separate registry:

       MCWorkingCopy allManagers collect: #package

- Bert -
(0013874)
hirzel   
09-08-10 17:21   
Chris Muller on the Squeaklist

PackageInfo subclasses do not add any extra inst-vars, and they
shouldn't because the primary method of persistence, Monticello, does
not persist objects, only code. That code can be run at various times
to assist with configuration. They only override certain methods that
declare the structure and contents of the package.

Creating a PackageInfo subclass is no different than creating a
subclass of any other class:

PackageInfo subclass: #MyPackageInfo
       instanceVariableNames: ''
       classVariableNames: ''
       poolDictionaries: ''
       category: 'MyPackage-Info'

For example, if a package requires several system changes (like
Stephane Rollandin's muO), then one could override #patchNames to,
instead of answering an empty Array, answer an Array of strings which
are the names of the change-set files, in order, that should be loaded
to make a running muO system.

Similarly, the MyPackageInfo subclass can also report its *immediate*
dependencies in terms of other packages by overriding
#prerequisitePackageNames:

prerequisitePackageNames
       ^ super prerequisitePackageNames ,
               { MyPrerequisitePackageInfo packageName.
               MyOtherPrerequisitePackageInfo packageName }

Even by only declaring immediate dependencies of each package, the
full dependency tree can then be calculated in load-dependent order by
the computer..

Personally, what I like about PackageInfo is that it is very open and
lightweight. *I* added the notion of #prerequisitePackageNames to
handle the dependencies myself. But if this is of general interest we
should fold it into the trunk.

This and more documentation is available on the wiki:

   http://wiki.squeak.org/squeak/3329 [^]
   http://wiki.squeak.org/squeak/6155 [^]

 - Chris
(0013875)
hirzel   
09-08-10 17:22   
Chris Muller:

> Personally, what I like about PackageInfo is that it is very open and
> lightweight.

.. AND, that it is already part of core Squeak, and SCM tool agnostic...