[bjam] SHELL and EXIT changes.

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

[bjam] SHELL and EXIT changes.

Rene Rivera
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/ ? )
]

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=".

[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 =COMMAND= can be used as an alias for =SHELL=.

Please test for both compatibility with the existing uses of SHELL. And
of course if you have a need with the new functionality. There are some
minor unit test at boost-root/tools/jam/test.

Hopefully bjam is now in a state that I can make a 3.1.12 release. That
is if no one has objections.


...And i just saw Jim made some QNX fixes :-)


--
-- 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
_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: [bjam] SHELL and EXIT changes.

David Abrahams
Rene Rivera <[hidden email]> 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.

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

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


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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: [bjam] SHELL and EXIT changes.

Rene Rivera
David Abrahams wrote:

> Rene Rivera <[hidden email]> 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
_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: [bjam] SHELL and EXIT changes.

Rene Rivera
Rene Rivera wrote:

> David Abrahams wrote:
>> Rene Rivera <[hidden email]> writes:
>>
>>> 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.

Aha, found it! The Perforce/Jambase defines:

#
# Backwards compatibility with jam 1, where rules were uppercased.
#

rule BULK { Bulk $(<) : $(>) ; }
rule FILE { File $(<) : $(>) ; }
rule HDRRULE { HdrRule $(<) : $(>) ; }
rule INSTALL { Install $(<) : $(>) ; }
rule LIBRARY { Library $(<) : $(>) ; }
rule LIBS { LinkLibraries $(<) : $(>) ; }
rule LINK { Link $(<) : $(>) ; }
rule MAIN { Main $(<) : $(>) ; }
rule SETUID { Setuid $(<) ; }
rule SHELL { Shell $(<) : $(>) ; }
rule UNDEFINES { Undefines $(<) : $(>) ; }


I'll change the docs to reflect the SHELL name.


--
-- 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
_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: [bjam] SHELL and EXIT changes.

David Abrahams
In reply to this post by Rene Rivera
Rene Rivera <[hidden email]> writes:

> David Abrahams wrote:
>> Rene Rivera <[hidden email]> 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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost-build