Note: This web site is only kept up to date for OSG Software
1.2 (VDT 2.0.0). If you are looking for information for the most recent
release, the RPM-based OSG Software 3.0, please see
the OSG documentation web site
Pacman standards for the VDT
Having created a large number of Pacman packages for the VDT, I have
become rather picky about how we setup our Pacman packages. While I
may seem overly picky about these details, I strongly believe that
they make the difference between a merely adequate installation
experience and a superior installation experience. The goal for the
VDT is to provide a superior installation experience.
With this goal in mind, I have developed a set of rules for Pacman
packages in the VDT. I'm strict about these rules, and I yell and
stomp my feet whenever people break them.
- Every package must log information into the vdt-install.log
file. At a minimum, there must be a header that looks exactly like
this, except with the correct software name and date:
# Building GPT 3.1 at Mon Jan 26 14:49:37 CST 2004
Yes, always use that number of hash symbols. It make it easy to look
for inforation in the vdt-install.log file.
In addition, the log should contain as much other information as
possible. If you have a script that installs the software, everything
should be put into the log file. If you build software, the output of
the build should be put into the log file. This log file is
essential, and has often helped us solve problems.
- If you want to give the user a bunch of information that does not
require immeidate action do not print it to the screen. Instead, print
a short note to the screen, and everything else in the postinstall
directory. Usually information in the postinstall directory should be
in the README. For example, you might say:
We had to make certain choices about how to configure Condor.
For information about these choices and guidance on how to change
them, please see the postinstall/README file.
- During installation, print as little information to the screen as
possible. If there are serious errors, you can print those, and
fail. Users do not need to see lots of messages about the random
details of installation, like "updating .la files... changing
gatekeeper config..." because they don't mean much to most
users. Besides, it makes everything scroll off the screen, and they
can no longer see what happened earlier. These messages can go into
the log file, or the postinstall file.
- During installation, you should only ask users questions that are
essential. If you can skip any questions and use reasonable defaults,
please do so. If you have to have a lot of questions answered, perhaps
they are best put into a script that users can run at
post-installation time. Realize that few software packages are used by
all users, and many users don't know the answers until they have
worked with the software a bit. Have pity on the users, and don't
expecdt too much out of them during installation.
- Packages must be installable as root and non-root. Many users want
to install as non-root, to see how things work. This has been a
selling point of the VDT. If some functionality has to be turned off
because the installation was not done as root, so be it. Note this
briefly on the screen, and provide details in the postinstall/README
file about how to get back that additional functionality.
- Prefer to install software as binaries instead of compiling from
source. Compiling from source is often tricky: users have poorly setup
computers with outdated or missing tools, and compilation will
fail. Also, compilation is usually slower. Yes, it is a pain to
provide the correct binaries and decide which binaries to
install, but it makes users happier. Think like a user, not a
programmer. If you are sad that users don't have the source, install
(but don't compile) the source as well, or provide a file that tells
users how to get the source.
- Be careful about installing with the correct permissions. In some
situations, when you unwind a tarball on a computer and you are root,
the user and group are preserved, even though they may not make sense
on this computer. Then users ask us things like, "why is this file
owned by user 8407?".
- Pacman files must contain a clear description.
- Pacman files must contain a URL that tells users where to learn
more about the package. Often the VDT web page is insufficient. For
instance, for Monalisa, you want to give the Monalisa web page, not
the VDT web page.
- Pacman files should be named with capital letters and hypens for
spaces. For example, we have Globus-Environment.pacman. Pacman file names
must end in .pacman, or Pacman can't find them. Pacman file names
should rarely have version numbers in them.
- Pacman files should not have any tab characters in them, only
spaces. This makes the files display neatly in both terminal windows
and web browsers.