search

easybuilders / easybuild-framework

EasyBuild is a software installation framework in Python that allows you to install software in a structured and robust way.
https://easybuild.io
GNU General Public License v2.0
148 stars 201 forks source link

Fix a manpage for EasyBuild #271

Open fgeorgatos opened 11 years ago

fgeorgatos commented 11 years ago

Hi,

I made an example draft in ReST (rst2man parses it nicely); feel free to hack it around as you fancy.

[root@ui10 rst2man]# cat eb.txt 
=========
EasyBuild
=========

----------------------------------------------------------------------------------------------------------------------------------------------------------
EasyBuild is a software build and installation framework written in Python that allows you to install software in a structured, repeatable and robust way.
----------------------------------------------------------------------------------------------------------------------------------------------------------

:Author: fotis@cern.ch
:Date:   2012-10-12
:Copyright: CC-BY-SA
:Version: 0.1
:Manual section: 8
:Manual group: administrator commands

.. TODO: Fotis Georgatos <Fotis.Georgatos@uni.lu> # Add other manpage authors as needed

SYNOPSIS
========

  eb.py [options] easyconfig [..]

DESCRIPTION
===========

Build a software package based on easyconfig (or parse a directory). 
Provide one or more easyconfigs or directories, use -h or --help more information.

OPTIONS
=======

  -h, --help            show the help message and exit

  Basic options:
    Basic runtime options for EasyBuild.

    -b BLOCKS, --only-blocks=BLOCKS
                        Only build blocks blk[,blk2]
    -d, --debug         log debug messages
    -f, --force         force to rebuild software even if it's already
                        installed (i.e. can be found as module)
    --job               will submit the build as a job
    -k, --skip          skip existing software (useful for installing
                        additional packages)
    -l                  log to stdout
    -r PATH, --robot=PATH
                        path to search for easyconfigs for missing
                        dependencies
    -s STOP, --stop=STOP
                        stop the installation after certain step (valid: cfg,
                        source, patch, prepare, configure, make, install,
                        test, postproc, cleanup, packages)
    --strict=STRICT     set strictness level (possible levels: ignore, warn,
                        error)

  Software build options:
    Specify software build options; the regular versions of these options
    will only search for matching easyconfigs, while the --try-X versions
    will cause EasyBuild to try and generate a matching easyconfig based
    on available ones if no matching easyconfig is found (NOTE: best
    effort, might produce wrong builds!)

    --software-name=NAME
                        build software with name

    --software-version=VERSION
                        build software with version

    --toolkit=NAME,VERSION
                        build with toolkit (name and version)

    --toolkit-name=NAME
                        build with toolkit name

    --toolkit-version=VERSION
                        build with toolkit version

    --amend=VAR=VALUE[,VALUE]
                        specify additional build parameters (can be used
                        multiple times); for example: versionprefix=foo or
                        patches=one.patch,two.patch)

    --try-software-name=NAME
                        try to build software with name (USE WITH CARE!)

    --try-software-version=VERSION
                        try to build software with version (USE WITH CARE!)

    --try-toolkit=NAME,VERSION
                        try to build with toolkit (name and version) (USE WITH CARE!)

    --try-toolkit-name=NAME
                        try to build with toolkit name (USE WITH CARE!)

    --try-toolkit-version=VERSION
                        try to build with toolkit version (USE WITH CARE!)

    --try-amend=VAR=VALUE[,VALUE]
                        try to specify additional build parameters (can be
                        used multiple times); for example: versionprefix=foo
                        or patches=one.patch,two.patch) (USE WITH CARE!)

  Override options:
    Override default EasyBuild behavior.

    -C CONFIG, --config=CONFIG
                        path to EasyBuild config file
                        [default: $EASYBUILDCONFIG or easybuild/easybuild_config.py]
    -e CLASS, --easyblock=CLASS
                        loads the class from module to process the spec file
                        or dump the options for [default: Application class]
    -p, --pretend       does the build/installation in a test directory
                        located in $HOME/easybuildinstall [default:
                        $EASYBUILDINSTALLDIR or installPath in EasyBuild
                        config file]
    -t, --skip-tests    skip testing

  Informative options:
    Obtain information about EasyBuild.

    -a, --avail-easyconfig-params
                        show available easyconfig parameters
    --dump-classes      show list of available classes
    --search=SEARCH     search for module-files in the robot-directory
    -v, --version       show version

    --dep-graph=depgraph.<ext>
                        create dependency graph

  Regression test options:
    Run and control an EasyBuild regression test.

    --regtest           enable regression test mode
    --regtest-online    enable online regression test mode
    --sequential        specify this option if you want to prevent parallel
                        build
    --regtest-output-dir=REGTEST_OUTPUT_DIR
                        set output directory for test-run
    --aggregate-regtest=AGGREGATE_REGTEST
                        collect all the xmls inside the given directory and
                        generate a single file

PROBLEMS
========

1. EasyBuild does not make coffee ; read Linux Coffee-HOWTO

SEE ALSO
========

 * `EasyBuild homepage <http://hpcugent.github.com/easybuild/>`__
 * `EasyBuild framework repository <https://github.com/hpcugent/easybuild>`__
 * `EasyBuild experimental repository <https://github.com/fgeorgatos/easybuild.experimental>`__
 * ``man 8 eb``

BUGS
====

 * "this software has no bugs - only features" (TM)

 * --try-X versions
    will cause EasyBuild to try and generate a matching easyconfig based
    on available ones if no matching easyconfig is found.
    NOTE: this is best effort and might produce wrong builds!

 * Discussion about the tool's specification is still open.

 * `Report any unknown issue at the github tracker <https://github.com/hpcugent/easybuild/issues>`__
fgeorgatos commented 11 years ago

hm... I come to realize that CC-BY-SA may not be proper since this is derivative work. Modify it as you see fit.

boegel commented 11 years ago

We should have a script that generates this, so e.g. the list of options remains up-to-date.

Would you be willing to look into that? The script should go into easybuild/scripts.

fgeorgatos commented 11 years ago

On Mon, Oct 22, 2012 at 11:13 AM, Kenneth Hoste notifications@github.comwrote:

We should have a script that generates this, so e.g. the list of options remains up-to-date.

Would you be willing to look into that? The script should go into easybuild/scripts.

If I am to do that, I might as well recycle the output of eb -h AS-IS via a shell script; and automagically produce the .rst; but, is that going to be good enough? (I doubt).

Fotis

JensTimmerman commented 11 years ago

I would prefer you wrote it in python, not shell

you could use this

>>> from optparse import OptionParser
>>> from easybuild.main import add_cmdline_options
>>> parser = OptionParser()
>>> add_cmdline_options(parser)
>>> helpmessage = parser.format_help()

But shell would be acceptable...

JensTimmerman commented 11 years ago

extending the parser's formatter to directly generate a man page would even be better! (We could look into that in generaloption.py from VSC-tools ;-))

fgeorgatos commented 11 years ago

Hi there,

Two things, the first one is a bit high priority:

1) There's a typo in the output of eb -h which would confuse newcomers: EASYBUILDINSTALLDIR vs EASYBUILDINSTALLPATH # please fix!

2) I have produced another manpage in rst format, based on v1.0's output; alas, it was not possible to automate the procedure, see at the end why

=========
EasyBuild
=========

----------------------------------------------------------------------------------------------------------------------------------------------------------
EasyBuild is a software build and installation framework written in Python that allows you to install software in a structured, repeatable and robust way.
----------------------------------------------------------------------------------------------------------------------------------------------------------

:Author: Fotis Georgatos <Fotis.Georgatos@cern.ch> # for the manpage
:Date:   2012-11-15
:Copyright: CC-BY-SA
:Version: 1.0
:Manual section: 1
:Manual group: General commands

.. TODO: Fotis Georgatos <Fotis.Georgatos@uni.lu> # Add other manpage authors as needed

SYNOPSIS
========

  ``eb`` [options] easyconfig [..]

DESCRIPTION
===========

Build a software package based on easyconfig (or parse a directory). 
Provide one or more easyconfigs or directories, use -h or --help more information.

OPTIONS
=======

Usage: eb [options] easyconfig [..]

Builds software based on easyconfig (or parse a directory) Provide one or more
easyconfigs or directories, use -h or --help more information.

Options:
  -h, --help            show this help message and exit

  Basic options:
    Basic runtime options for EasyBuild.

    -b BLOCKS, --only-blocks=BLOCKS
                        Only build blocks blk[,blk2]
    -d, --debug         log debug messages
    -f, --force         force to rebuild software even if it's already
                        installed (i.e. can be found as module)
    --job               will submit the build as a job
    -k, --skip          skip existing software (useful for installing
                        additional packages)
    -l                  log to stdout
    -r, --robot         path to search for easyconfigs for missing
                        dependencies (default: easybuild-easyconfigs install
                        path)
    -s STOP, --stop=STOP
                        stop the installation after certain step (valid: cfg,
                        source, patch, prepare, configure, make, install,
                        test, postproc, cleanup, extensions)
    --strict=STRICT     set strictness level (possible levels: ignore, warn,
                        error)

  Software build options:
    Specify software build options; the regular versions of these options
    will only search for matching easyconfigs, while the --try-X versions
    will cause EasyBuild to try and generate a matching easyconfig based
    on available ones if no matching easyconfig is found (NOTE: best
    effort, might produce wrong builds!)

    --software-name=NAME
                        build software with name

    --software-version=VERSION
                        build software with version

    --toolchain=NAME,VERSION
                        build with toolchain (name and version)

    --toolchain-name=NAME
                        build with toolchain name

    --toolchain-version=VERSION
                        build with toolchain version

    --amend=VAR=VALUE[,VALUE]
                        specify additional build parameters (can be used
                        multiple times); for example: versionprefix=foo or
                        patches=one.patch,two.patch)

    --try-software-name=NAME
                        try to build software with name (USE WITH CARE!)

    --try-software-version=VERSION
                        try to build software with version (USE WITH CARE!)

    --try-toolchain=NAME,VERSION
                        try to build with toolchain (name and version) (USE
                        WITH CARE!)

    --try-toolchain-name=NAME
                        try to build with toolchain name (USE WITH CARE!)

    --try-toolchain-version=VERSION
                        try to build with toolchain version (USE WITH CARE!)

    --try-amend=VAR=VALUE[,VALUE]
                        try to specify additional build parameters (can be
                        used multiple times); for example: versionprefix=foo
                        or patches=one.patch,two.patch) (USE WITH CARE!)

  Override options:
    Override default EasyBuild behavior.

    -C CONFIG, --config=CONFIG
                        path to EasyBuild config file [default:
                        $EASYBUILDCONFIG or easybuild/easybuild_config.py]

    -e CLASS, --easyblock=CLASS
                        loads the class from module to process the spec file
                        or dump the options for [default: Application class]

    -p, --pretend       does the build/installation in a test directory
                        located in $HOME/easybuildinstall [default:
                        $EASYBUILDINSTALLPATH or install_path in EasyBuild
                        config file]

    -t, --skip-test-cases
                        skip running test cases

  Informative options:
    Obtain information about EasyBuild.

    -a, --avail-easyconfig-params
                        show available easyconfig parameters

    --list-easyblocks=LIST_EASYBLOCKS
                        show list of available easyblocks

    --search=STR        search for module-files in the robot-directory

    -v, --version       show version

    --dep-graph=depgraph.<ext>
                        create dependency graph

  Regression test options:
    Run and control an EasyBuild regression test.

    --regtest           enable regression test mode
    --regtest-online    enable online regression test mode
    --sequential        specify this option if you want to prevent parallel build

    --regtest-output-dir=DIR
                        set output directory for test-run

    --aggregate-regtest=DIR
                        collect all the xmls inside the given directory and generate a single file

PROBLEMS
========

#1. EasyBuild does not make coffee yet ; read Linux Coffee-HOWTO instead

SEE ALSO
========

 * man eb # <-- YOU ARE HERE
 * EasyBuild homepage: http://hpcugent.github.com/easybuild/ # general information
 * EasyBuild framework repository: https://github.com/hpcugent/easybuild-framework # source
 * EasyBuild experimental repository: https://github.com/fgeorgatos/easybuild.experimental # area51

BUGS
====

 * "this software has no bugs - only features" (TM) ; read below about how to find them

 * Report any unknown issue at the github tracker: https://github.com/hpcugent/easybuild/issues

OK, in order to automatically produce the manpage, we need to fix:

I had to do this in the quick'n'dirty manner since I have the uni.lu folks now using the tool!

If you need to, I can submit to you the produced file, mine is at a destination like: /opt/apps/default/software/easybuild/1.0/share/man/man1/eb.1 but I think you're big boys and can make it with rst2man just fine :-)

hey, a big applause from this end for the SC12 rollout!

Fotis

boegel commented 11 years ago

Hi Fotis,

Can you open an issue for 1), with a critical label in the easybuild-framework repo? I know it's an easy fix, and we should fix it ASAP, but we're not going to ship a new release just because of this.

It's important to have a track record on issues, even the smallest ones.

Man page looks good, we can clean up the help output as a part of the issue for 1) to automate the procedure.

K.

Op 15 Nov 2012 om 10:31 heeft Fotis Georgatos notifications@github.com het volgende geschreven:

Hi there,

Two things, the first one is a bit high priority:

1) There's a typo in the output of eb -h which would confuse newcomers: EASYBUILDINSTALLDIR vs EASYBUILDINSTALLPATH # please fix!

2) I have produced another manpage in rst format, based on v1.0's output; alas, it was not possible to automate the procedure, see at the end why

EasyBuild

EasyBuild is a software build and installation framework written in Python that allows you to install software in a structured, repeatable and robust way.

:Author: Fotis Georgatos Fotis.Georgatos@cern.ch # for the manpage :Date: 2012-11-15 :Copyright: CC-BY-SA :Version: 1.0 :Manual section: 1 :Manual group: General commands

.. TODO: Fotis Georgatos Fotis.Georgatos@uni.lu # Add other manpage authors as needed

SYNOPSIS

eb [options] easyconfig [..]

DESCRIPTION

Build a software package based on easyconfig (or parse a directory). Provide one or more easyconfigs or directories, use -h or --help more information.

OPTIONS

Usage: eb [options] easyconfig [..]

Builds software based on easyconfig (or parse a directory) Provide one or more easyconfigs or directories, use -h or --help more information.

Options: -h, --help show this help message and exit

Basic options: Basic runtime options for EasyBuild.

-b BLOCKS, --only-blocks=BLOCKS
                    Only build blocks blk[,blk2]
-d, --debug         log debug messages
-f, --force         force to rebuild software even if it's already
                    installed (i.e. can be found as module)
--job               will submit the build as a job
-k, --skip          skip existing software (useful for installing
                    additional packages)
-l                  log to stdout
-r, --robot         path to search for easyconfigs for missing
                    dependencies (default: easybuild-easyconfigs install
                    path)
-s STOP, --stop=STOP
                    stop the installation after certain step (valid: cfg,
                    source, patch, prepare, configure, make, install,
                    test, postproc, cleanup, extensions)
--strict=STRICT     set strictness level (possible levels: ignore, warn,
                    error)

Software build options: Specify software build options; the regular versions of these options will only search for matching easyconfigs, while the --try-X versions will cause EasyBuild to try and generate a matching easyconfig based on available ones if no matching easyconfig is found (NOTE: best effort, might produce wrong builds!)

--software-name=NAME
                    build software with name

--software-version=VERSION
                    build software with version

--toolchain=NAME,VERSION
                    build with toolchain (name and version)

--toolchain-name=NAME
                    build with toolchain name

--toolchain-version=VERSION
                    build with toolchain version

--amend=VAR=VALUE[,VALUE]
                    specify additional build parameters (can be used
                    multiple times); for example: versionprefix=foo or
                    patches=one.patch,two.patch)

--try-software-name=NAME
                    try to build software with name (USE WITH CARE!)

--try-software-version=VERSION
                    try to build software with version (USE WITH CARE!)

--try-toolchain=NAME,VERSION
                    try to build with toolchain (name and version) (USE
                    WITH CARE!)

--try-toolchain-name=NAME
                    try to build with toolchain name (USE WITH CARE!)

--try-toolchain-version=VERSION
                    try to build with toolchain version (USE WITH CARE!)

--try-amend=VAR=VALUE[,VALUE]
                    try to specify additional build parameters (can be
                    used multiple times); for example: versionprefix=foo
                    or patches=one.patch,two.patch) (USE WITH CARE!)

Override options: Override default EasyBuild behavior.

-C CONFIG, --config=CONFIG
                    path to EasyBuild config file [default:
                    $EASYBUILDCONFIG or easybuild/easybuild_config.py]

-e CLASS, --easyblock=CLASS
                    loads the class from module to process the spec file
                    or dump the options for [default: Application class]

-p, --pretend       does the build/installation in a test directory
                    located in $HOME/easybuildinstall [default:
                    $EASYBUILDINSTALLPATH or install_path in EasyBuild
                    config file]

-t, --skip-test-cases
                    skip running test cases

Informative options: Obtain information about EasyBuild.

-a, --avail-easyconfig-params
                    show available easyconfig parameters

--list-easyblocks=LIST_EASYBLOCKS
                    show list of available easyblocks

--search=STR        search for module-files in the robot-directory

-v, --version       show version

--dep-graph=depgraph.<ext>
                    create dependency graph

Regression test options: Run and control an EasyBuild regression test.

--regtest           enable regression test mode
--regtest-online    enable online regression test mode
--sequential        specify this option if you want to prevent parallel build

--regtest-output-dir=DIR
                    set output directory for test-run

--aggregate-regtest=DIR
                    collect all the xmls inside the given directory and generate a single file

PROBLEMS

1. EasyBuild does not make coffee yet ; read Linux Coffee-HOWTO instead

SEE ALSO

BUGS

OK, in order to automatically produce the manpage, we need to fix:

the way the output is produced had to be tuned a bit for rst compliance: try a diff (being specific: more spaces should separate options, otherwise rst2man complains) add the list of names of software developers and/or preferred mailing list to contact at follow Jens's advice overall ;-) I had to do this in the quick'n'dirty manner since I have the uni.lu folks now using the tool!

If you need to, I can submit to you the produced file, mine is at a destination like: /opt/apps/default/software/easybuild/1.0/share/man/man1/eb.1 but I think you're big boys and can make it with rst2man just fine :-)

hey, a big applause from this end for the SC12 rollout!

Fotis

— Reply to this email directly or view it on GitHub.