========================================================================

                              Home Page

The home page for pathmgr is at the following URL:

    http://www.serice.net/pathmgr/

========================================================================

                             Installation

General:
=======

pathmgr is primarily a Python script.  Just unpack it and run it like
any other Python script:

    python pathmgr.py --help

If you add the pathmgr directory to your PATH, you should be able to
run it as follows under both Unix and Windows:

    pathmgr ...

The examples below all assume pathmgr is in your PATH.



Running the Tests:
=================

Before using pathmgr, it is a good idea to run the included tests as
follows:

    # With feedback.
    python test/run.py

    # Without feedback.
    python test/run.py -q

========================================================================

                               Overview

The purpose of pathmgr is to allow developers to manage multiple,
mutually exclusive sets of PATHs because it is very common to need
your PATH set up one way for one project and a different way for a
different project and yet a third way for when you are not working on
a project etc.

On Unix operating systems, this is usually handled by logging out and
back in to get a fresh PATH followed by "sourcing" a script to add
directories to the PATH.  A similar approach works under Windows.  So
why does pathmgr exist?

pathmgr exists for the following reasons:

  1) pathmgr can remove elements from the PATH.  In fact, it can
     remove exactly the same set of directories that it previously
     added.  This lets you quickly correct mistakes or move to a
     different project with confidence that your PATH is correct, and
     if you are working remotely, you don't have to login again just
     to get a fresh PATH.

  2) pathmgr is portable.  If you work on cross-platform projects, you
     have to set up your path on different operating systems for
     different shells.  The "sourcing" solution cannot easily handle
     this scenario without duplicating the same paths in the scripts
     for each shell.  On the other hand, pathmgr stores your
     configuration in a reasonable XML format from which it portably
     generates correct paths on all platforms where Python runs.

  3) PATH Hygiene.  Because the "sourced" scripts are full shell
     scripts, they tend to collect cruft over time.  It is not
     uncommon for people to put there personal preferences in these
     files because who wouldn't like red text on a brown background.
     The XML file for pathmgr is limited to PATHs and nothing but
     PATHs making it a good candidate for version control.

========================================================================

                             Introduction

pathmgr has many options.  If you don't see what you are looking for
here, please read the following output for the details:

    pathmgr --help

Almost everything that can be done at the command line can be done via
XML files and vice versa.  The names of the command-line options
closely match the names of the XML elements.

The command you will likely run the most from the command line is just
the one that simply lists the path with one path element per line.
This makes it much easier to see what is in your PATH and to use diff
to see how it has changed:

    # List the PATH.
    pathmgr -l -q

Path entries can be added and removed from the command line too, but
in a production environment, you are likely to want to set up (at
least) one XML file that stores your PATH configuration for that
project.  A basic XML file will look something like the following:

    <pathmgr>

        <!-- Assuming this file is located in a "scripts" directory,
          == we want all paths to be relative to the top-level
          == directory which is one level up. -->
        <anchor>..</anchor>

        <!-- Set up default values for variables that the user can
          == override at the command line. -->
        <default>foo=bar</default>
        <default>spam=eggs</default>

        <!-- Set up your paths.  "after" directories are appended
          == to the path, and "before" directories are prepended.
          == The tags "append" and "prepend" can also be used. -->
        <before>${foo}/${spam}/bin</before>
        <after>../../../third-party/acme/widgets/bin</after>        

    </pathmgr>

If you are running Windows, given the XML file above, you can change
your PATH using the provided pathmgr.bat script as follows:

    # For Windows, use the provided pathmgr.bat which will be
    # picked up if you just type the "pathmgr" command.
    pathmgr --define=foo=baz ^
            --define=spam=quux ^
            scripts/pathmgr.xml

For Unix, just use command substitution with the `...` or $(...)
syntax or whaterver is supported by your shell:

    # For Unix, directly use command substitution.
    PATH=`pathmgr --define=foo=baz \
                  --define=spam=quux \
                  scripts/pathmgr.xml`
    export PATH

Finally, to undo the changes to your PATH, just run the exact same
command line but with the --clean option added as far to the left as
possible.  The Windows command above would be undone as follows:

    # Undo for Windows
    pathmgr --clean ^
            --define=foo=baz ^
            --define=spam=quux ^
            scripts/pathmgr.xml

========================================================================

                                MinGW

Note that the shell used by MinGW normalizes both command-line
parameters and environment variables (like PATH) before passing them
to native applications like the Python interpreter that runs the
pathmgr script!  This can make it *appear* as though pathmgr is not
honoring --normalize=off.

The solution to the MinGW problem is two fold.  First, use an XML
configuration file to pass paths to pathmgr to avoid MinGW's
normalization of command-line parameters.  For example:

    <pathmgr>
      <normalize>off</normalize>
      <remove>/c/foo/bar/baz</remove>
    </pathmgr>

Second, pipe the PATH into pathmgr instead of passing it through the
environment to avoid MinGW's normalization of environment variables.
For example:

    printf "$PATH" | pathmgr --origin=- --sep=: --uds=off foo.xml

To make this more convient, the "pathmgr-mingw" script is provided
which can be executed as follows:

    pathmgr-mingw foo.xml

To learn more about MinGW's normalization of command-line parameters
and environment variables, visit the following URL:

    http://www.mingw.org/wiki/Posix_path_conversion

========================================================================

                               Summary

The main thing to remember is that pathmgr does not directly alter
your PATH; instead, it prints out the new PATH to standard output.
You then need to somehow set the PATH for your shell using the new
PATH.  For Windows, this can be done easily by running the pathmgr.bat
wrapper which should take care of everything for you.  For Unix, this
can be done through command substitution as shown above.

========================================================================