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

From: Rene Rivera (grafik.list_at_[hidden])
Date: 2006-02-03 23:59:56

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. 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. 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?

>> 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. 
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 ;-)

>> [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.

--
-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. - http://redshift-software.com
-- rrivera/acm.org - grafik/redshift-software.com
-- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo