========================================================================
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:
..
foo=bar
spam=eggs
${foo}/${spam}/bin
../../../third-party/acme/widgets/bin
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:
off
/c/foo/bar/baz
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.
========================================================================