Andreas,

I'm going to be in meetings all day long, but I do have an answer for
question #1 ... I'll reply in more detail to the other questions as I get
time.

1) #includes: vs. #requires:

I've submitted Issue 76
(http://code.google.com/p/metacello/issues/detail?id=76) about improving the
documentation for #includes: vs. #requires:.

Let's assume that we have package A that #requires: package B and #includes:
package C.

If one #loads: package A, the the load order would be:

  B, A, C

So the immediate distinction is that B will be loaded _before_ A due to the
#requires: and C will be loaded due to the #includes:. Typically an included
package will require the parent (i.e., package C requires: package A).

The utility for #includes: comes into play another package #requires:
package A. In the case where package D #requires: A, the load order for a
#loads:  D would be:

  B, A, C, D

Two things are happening, first is the obvious that package C is included
before package D. Secondly, there is in implicit #requires: from D to C
(i.e. D #requires: C is implied). 

#includes is used quite extensively for Seaside30 where an expression like
the following is used:

	spec for: #common do: [
                spec
			package: 'Javascript-Core' 
				with: [ spec requires: #('Seaside-Core' 'Seaside-Canvas' ). ];
			package: 'JQuery-Core' 
				with: [ spec requires: #('Javascript-Core' ). ]].
	spec for: #squeakCommon do: [
		spec
			package: 'Javascript-Core' 
				with: [ spec includes: #('Javascript-Pharo-Core' ) ]].

'JQuery-Core' requires: 'Javascript-Core', but when 'Javascript-Core' is
required. By using includes, we only need to inform 'Javascript-Core' to
drag 'Javascript-Pharo-Core' along with it.

Whereas if we only had the #requires: mechanism, we'd need to duplicate
every 'Javascript-Core'   #requires: with a #requires: for 
'Javascript-Pharo-Core'

Dale


Teleplacer wrote:
> 
> Hi -
> 
> I've been trying to wet my feet with Metacello a little by writing a 
> ConfigurationOfWebClient and in the process I've come across various 
> things that I don't understand or don't know how to express. The 
> configuration itself can be found here:
> 
> 	http://www.squeaksource.com/MetacelloRepository
> 
> Here are the questions I'm having:
> 
> 1) #includes: vs. #requires:
> What is the difference between #includes: and #requires:? They sound 
> entirely interchangeable, in particular after reading the tutorial which 
> states:
> 
> 	"When you use the #includes: directive, you are not only specifying 
> that the listed packages should be loaded when the parent package is 
> loaded, but that the #included: packages should be loaded _before_ any 
> packages that require the parent package."
> 
> I would expect that precise behavior for required packages, i.e., if Foo 
> requires: Bar then Bar is loaded before Foo if some other package 
> requires: Foo. What am I missing?
> 
> 2) Why is HelpSystem not loaded?
> In my configuration, baseline specifies that HelpSystem is required for 
> WebClient-Help:
> 
> 		"Documentation doesn't require Core/Tests, but HelpSystem"
> 		spec package: 'WebClient-Help' with:[spec requires: 'HelpSystem'].
> 
> 		spec project: 'HelpSystem' with:[
> 			spec
> 				className: 'ConfigurationOfHelpSystem';
> 				repository: 'http://www.squeaksource.com/MetacelloRepository'
> 		].
> 
> However, when executed, Metacello goes through the motions but doesn't 
> actually *load* any version of HelpSystem (I can see it 'fetch' the 
> packages but not load them). It even calls the postLoadDoIt on it (which 
> fails since nothing was loaded). What am I doing wrong?
> 
> 3) When exactly is HelpSystem loaded?
> 
> What I'm wondering about in the above is that HelpSystem should only be 
> loaded if WebClient-Help is being loaded. Is this implicitly part of 
> specifying a 'project' instead of a 'package'? Or is there some other 
> way of specifying that?
> 
> I guess really the question here is what entities get loaded implicitly 
> simply by declaring them (packages for sure, any others?) and what 
> entities need to be 'required' in order to be loaded?
> 
> 4) How does one define dependencies that differ based on platform?
> 
> In WebClient, the WebClient-HTTP package requires WebClient-Core and 
> -only for: #pharo- also WebClient-Pharo. How does one express that 
> there's an additional dependency for WebClient-HTTP that only exists 
> for: #pharo? The config currently specifies:
> 
> 	spec for: #common do:[
> 		" ... "
> 		spec package: 'WebClient-HTTP' with:[spec requires: 'WebClient-Core'].
> 		" ... "
> 	].
> 
> 	spec for: #pharo do:[
> 		"Just the fact it exists; no requirements here"
> 		spec package: 'WebClient-Pharo'.
> 	].
> 
> Which means that WebClient-Pharo will be loaded on Pharo by default but 
> it's missing the fact that WebClient-Pharo is in fact a requirement for 
> WebClient-HTTP (but only on that platform). How is that best expressed?
> 
> 5) Bootstrapping Metacello?
> 
> I found that most of the ConfigurationsOfXXX include some code to 
> 'bootstrap' Metacello in some form. There appear to be variants on the 
> code; is there a "canonical bootstrap method" that should be used?
> 
> 6) A standard Configuration template?
> 
> The Metacello tutorial is very useful as far as the configuration goes 
> but it falls short of getting into the details of what it means to 
> provide a 'working' configuration. Testing the configuration isn't 
> covered (is there a way to get back to a 'clean' state?); bootstrapping 
> isn't covered; the meaning of #isMetacelloConfig, 
> #metacelloVesion:loads:, #lastMetacelloVersionLoad and several other 
> -seemingly random- methods that can be found on most -but not all- of 
> the configurations. There is no indication on what these do, if they're 
> required, recommended, or optional. Is there some 'standard' 
> Configuration template that people can use to avoid guessing about which 
> parts of the boilerplate to copy from some other configuration?
> 
> That's it for now. Thanks for any insights on any of these issues.
> 
> Cheers,
>    - Andreas
> 
> 
> 

-- 
View this message in context: http://forum.world.st/Metacello-questions-tp2132073p2132976.html
Sent from the Squeak - Dev mailing list archive at Nabble.com.