Re: [Boost-build] [bjam] SHELL and EXIT changes.

From: David Abrahams (dave_at_[hidden])
Date: 2006-02-04 15:02:10

Rene Rivera <grafik.list_at_[hidden]> writes:

> David Abrahams wrote:
>> Rene Rivera <grafik.list_at_[hidden]> writes:
>> 
>>> I just checked in the changes I talked about earlier with regards to 
>>> adding options to the SHELL/COMMAND builtin. In the process I also added 
>>> to the EXIT builtin the ability to specify a result value to exit with. 
>>> I needed it to be able to implement a very minimal unit test facility 
>>> for testing the SHELL changes. QuickBook documentation for both is also 
>>> updated:
>>>
>>> [pre
>>> rule EXIT ( /message/ * : /result-value/ ? )
>>> ]
>> 
>> 
>> Nitty:
>> I'm not sure you should italicize parameter names; it's just bjam
>> code.  If you meant for them to be replaceable it would be 
>> 
>>   [pre
>>   EXIT ( [~message] : [~result-value] )
>>   ]
>> 
>> or something, but then you wouldn't be writing it as a rule
>> declaration.
>
> Well; First, the [~] replaceable just got added today and the docs got 
> written a few days ago. 

There's always escaping to BoostBook... when it works ;-)

> Second, I want to use the rule syntax to be as 
> clear as possible since that's the syntax we explain further up in the 
> docs. 

Sure.

> I'm using the italics so that it matches the same text in the 
> explanation. But I don't really care what style is actually used, just 
> that it be the same in both context, and different within both
> context. 

> _Suggestions welcome_ Underline? Bold/emphasis? Do we have other
> choices?  How are replaceables styled?

As italic, which is why I thought it might be confusing with the
replaceable text.  On the other hand, typically replaceable text is
not rendered in a monospace font, so maybe it'll be fine.

My point is that replaceable text should be used in a context that
looks like a /usage/ example.  When writing a declaration, you should
use some distinct formatting.

>>> Blurts out the /message/ to stdout and then exits with a failure status 
>>> if no /result-value/ is given, otherwise it exits with the given 
>>> /result-value/.
>>>
>>> "=Echo=", "=echo=", "=Exit=", and "=exit=" are accepted as aliases for 
>>> =ECHO= and =EXIT=, since it is hard to tell that these are built-in 
>>> rules and not part of the language, like "=include=".
>> 
>> Wouldn't that same logic hold for every builtin rule?  Why are these
>> special?
>
> Hmm, good question. I don't have an answer, and the Perforce original 
> authors are not likely to answer even if we asked. I remember you 
> mentioning something about the builtin Jambase use Camel-Case for
> rules. 

Yup.  And all the truly builtin rules are UPPERCASE.

> So if that's the case then I can maybe see devoting lower-case to 
> keywords, Camel-Case to rules, and UPPER-CASE to builtin rules. Not that 
> I would endorse such use of syntax for the simple reason of 
> distinguishing types of items. i.e. I'm not an LPCSTR kinda person
> ;-)

Me neither.  It just doesn't seem worth wasting code, or explanation,
on circumventing the convention in this case.

>
>>> [pre
>>> rule SHELL ( /command/ : * )
>>> ]
>>>
>>> =SHELL= executes /command/, and then returns the standard output of 
>>> /command/. =SHELL= only works on platforms with a =popen()= function in 
>>> the C library. On platforms without a working =popen()= function, 
>>> =SHELL= is implemented as a no-op. =SHELL= works on Unix, MacOS X, and 
>>> most Windows compilers. =SHELL= is a no-op on Metrowerks compilers under 
>>> Windows. There is a variable set of allowed options as additional arguments:
>>>
>>> [variablelist
>>>      [[=exit-status=] [In addition to the output the result status of 
>>> the executed command is returned as a second element of the result.]]
>>>      [[=no-output=] [Don't capture the output of the command. Instead an 
>>> empty ("") string value is returned in place of the output.]]
>>> ]
>>>
>>> Because the Perforce/Jambase defines a =Shell= rule which hides the 
>>> builtin
>> 
>> Why would it?  Jam is case sensitive.
>
> Hm, another good question :-) Truthfully I added the COMMAND alias when 
> a user complained about not being able to access the builtin through the 
> SHELL name. So I'm not sure where the other name came from. I wrote the 
> above from old memories :-\
>
> Perhaps that user is watching and can volunteer a rational.

Seems to me that the explanation just complicates the doc, which makes
the feature harmful on the whole.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com