ant-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "David Weintraub" <qazw...@gmail.com>
Subject Re: Target description format using -projecthelp
Date Tue, 11 Dec 2007 14:59:52 GMT
You're putting too much in your description attributes. The
description attribute does two things: It marks which targets are
"external" -- that is targets the user should run, and it helps
(merely helps) the user to remember which target does what.

The "ant -projecthelp" will only display targets that have a
description (thus hiding targets that a user doesn't execute
directly). The Eclipse IDE can hide internal targets when displaying a
list of targets in a build.xml file too. Thus, you should never use
the "description" attribute when you define internal targets. It will
merely confuse the user which targets should be used.

The description itself should be a short reminder of what the target
does -- longer than about 70 characters. Simple descriptions like
"CruiseControl main target: Cleans, builds, archives)", or "Builds the
project into the deploy directory".

Greater detail and documentation should really be done via comments
inside your build.xml file.

For example:

<target name="init_performance_run"
     depends="display_usage_message"
     description="Captures starting date/time and cleans up">

    <!--This target performs the following initializations:       -->
    <!-- * Capture the starting date/time of a run.                -->
    <!-- * Clean up files from previous runs."                       -->


Of course, if the user is not suppose to run the
"init_performance_run" target, you should not put in a description
attribute, so it won't display when a user does "ant -projecthelp":

<target name="init_performance_run"
     depends="display_usage_message">

    <!--This target performs the following initializations:       -->
    <!-- * Capture the starting date/time of a run.                -->
    <!-- * Clean up files from previous runs."                       -->

Some people even start internal build targets with an underscore:

<target name="_init_performance_run"
     depends="_display_usage_message">

    <!--This target performs the following initializations:       -->
    <!-- * Capture the starting date/time of a run.                -->
    <!-- * Clean up files from previous runs."                       -->


If you really need a command line ability to give longer descriptions
and documentation in your build.xml, create a target called "help" an
echo task to display your documentation:

<target name="help"
    description="Displays help (run as &quot;ant -e help&quot;)"

    <echo>
TARGET: init_performance_run
    This target performs performs the following functions:
         - Capture the starting date/time of a run
         - Clean up files from previous runs
    </echo>

Running "ant -e help" will display the description without the [echo]
being displayed on each line (that's why the reminder to use the -e in
the description). Otherwise, each echoed line will start with [echo]:

$ ant -project help

Main targets:

help:   Displays help (run as "ant -e help")

$ ant -e help

help:

    TARGET: init_performance_run
        This target performs performs the following functions:
             - Capture the starting date/time of a run
             - Clean up files from previous runs

$ ant help

help:
    [echo]
    [echo]  TARGET: init_performance_run
    [echo]      This target performs performs the following functions:
    [echo]         - Capture the starting date/time of a run
    [echo]         - Clean up files from previous runs
    [echo]


On Dec 10, 2007 9:00 PM, Z W <mpc8250@gmail.com> wrote:
> Hi
>
> In using -projecthelp with ant on Win XP, I found that the description
> column isn't too friendly with displaying a long description.
> In the display I got,
> C:ant -buildfile auto_perform_draft.xml -projecthelp
> Buildfile: auto_perform_draft.xml
>
> Main targets:
>  display_usage_message  This target displays the message on Run.
>  init_performance_run   This target performs the following initializations:
> - Capture the starting date/time of a run.     - Clean up files
> from previous runs.
>
> In the ant script, I have
>
> <target name="init_performance_run"
>
> depends="display_usage_message"
>
> description="This target performs the following initializations:
>
> - Capture the starting date/time of a run.
>
> - Clean up files from previous runs.">
>
> </target>
>
>
>
> Any advice on how I could achieve a display that look like this:
> Main targets:
>  display_usage_message  This target displays the message on Run.
> init_performance_run
> This target performs the following initializations:
>                                        - Capture the starting date/time of a
> run.
>                                        - Clean up files from previous runs.
>
> I need a nice formatting on the output display
>
> Thanks
>



-- 
--
David Weintraub
qazwart@gmail.com

---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@ant.apache.org
For additional commands, e-mail: user-help@ant.apache.org


Mime
View raw message