Below is the original guide (taken from
TeX ) for installing shared software on the department's computer systems. The guide is a bit out of date, but will act as a starting point for a new set of specifications about how and where software should be installed. The original document was written by
Jim Roche with input from others, it has been transcribed here by
KirkKelsey. Note that there are two figures missing from the original.
Let's keep the discussion between here, and the guide itself.
Discussion
Hazards
There is a clear prohibition on installing redundant software. A simple solution would be to include links is
/usr/grads/bin that include the version number. This allows a second person to link in a later version without conflict, and helps ensure the expected results.
--
KirkKelsey - 15 Feb 2006
Announcements
The existing guide makes a couple references to announcing software updates on the news groups, which are a little
de passe. I think the assumption should be that the
SharedSoftware page be updated, but should there be a page simply to announce that something has happened (akin to the
staff notices)?
--
KirkKelsey - 15 Feb 2006
UNIX Software Installation (GUIDE 15)
Introduction
This guide describes the University of Rochester Computer Science Department UNIX software installation procedures for the department Sun's and Vax. The guide only describes the general guidelines for installation of software. For more details on the specific tools the reader should refer to the on-line man pages for
ci,
co,
rcs,
co-all,
ci-all,
rcsdiff-all,
make,
rdist, and
rinstall.
To Install Or Not To Install
To install or not to install, that is the question. In general only software
that is of general use to the user community should be installed in a
publicly accessible location. If the software is useful to only a few
individuals within the department it should be installed in the
developers/supporters personal hierarchy.
Software that the installer
does not intend to maintain (i.e. provide bug fixes, install new versions,
respond to users complaints/questions, etc) should not be installed
in the publicly accessible directories. If you do not intend to provide support for the
tool, it belongs in your personal hierarchy.
Only software that has been tested should be installed.
Requirements
In order to have software systems that can be built, maintained,
and ported,
the department has adopted the following requirements for installing
new software on the UNIX machines.
- A man page for each executable, library, or shell script.
- A makefile that will create the appropriate output and install the executables, libraries, include files, documents and man pages.
- The source must be RCS'd in the appropriate source directory. This includes RCS'ing the makefile, man pages, documents, etc. Any file that cannot be generated should be RCS'd. Likewise, any file that can be regenerated should not be RCS'd (\ie\ y.tab.c should not be RCS'd since it can be created from the original yacc file).
- The software should be installed on every system it will run on. If it will run on the Vax, 680*0 and Sparcs, then it should be installed on all. If it will run in only one environment then it should only be installed in the environment in which it will run.
- The software must be distributed to all machines of like architectures. The current 680*0 servers are
castor, pollux, and gemini. The current Sparc servers are castor,=pollux=, gemini, and slate. The only remaining Vax is cayuga.
Where Things Go
To develop and install software properly you first need to know where
things go.
Where the Released Software Goes
The department has set up the following standard locations for
released software:
- /usr/staff
- Staff supported software
- /usr/grads
- Other department supported software (\Ie\ grad student or faculty)
- /usr/vision
- Vision related software supported by staff, faculty or grad student
Each of these hierarchies will contain, at a minimum, the following subdirectories:
- bin
- For executable binaries and shell scripts intended to be run directly by the user.
- lib
- For support files. Archive libraries, shell scripts or binaries that are used by executables in the bin directory, game score files, configuration files, etc.
- man
- Manual pages describing the tools placed in the bin and lib directories. Under the man directory there are the following subdirectories:
- man1 Describes user commands.
- man3 Describes archived library functions.
- man5 Describes the format of data files.
- man6 Describes games.
- include
- Include files that are of general use to the community. Not for include files that are needed just to compile a particular tool.
- doc
- Documents that provide more description than the man pages for the software systems installed in the bin and lib directories.
- src
- Contains the RCS'd versions of the source, makefile, man pages and other assorted files necessary to build the software package.
RCS subdirectories should not be used in the source tree hierarchy.
The bin, lib, man, include, and doc subdirectories exist on all of the Sun fileservers and all of the Vax. There is only one copy of the source, but through the magic of symbolic links and NFS it appears that there is a copy on each machine.
Where to Develop the Software
Development of the software should take place in the users personal
hierarchy. Under no circumstances should development be done in the
official source repository directories. The source directories are intended
only for the storage of the source files of the currently
installed software. Other users
should be able to go to the source directory and find the source for the
tools that are currently running. If development is taking place within
the source directories, other users will have difficulty in locating the
version of the source that is currently installed.
Users should never check out software within the source directories, nor
should makes ever be run in the source directories. There should never
be
.o files in the source directory. Since check outs aren't done in
the source directories, there should never be
.c, .h, .y, etc files
in the source directories.
If the filesystem where the developers home account resides does not
have enough
space for development of a software package, there is a
/scratch
filesystem
available from each of the Sun workstations for general purpose use.
This is short term storage, which is
currently being deleted on the first of every month. The rules for use of
the /scratch filesystem are published in the file
/scratch/README.
Installing the Software
Installing the source falls into two distinct categories. There
is software that
is developed locally and software packages which
are obtained elsewhere.
Hazards of Installing Software
There are some actions involved with installing software that if not done
carefully may have a detrimental affect on the entire user community.
- Do not install programs that duplicate existing programs.
- Do not reinstall a program that users are likely to be running at the time you do the installation. Due to the nature of NFS it is likely that you will cause the users execution of the program to fail.
- Do not rdist files from slate to the other file servers unless you are sure you know what you are doing. For example /usr/staff/bin on slate contains sparc binaries while on castor it contains 680*0 binaries. The safest method to distribute packages is with the rinstall command.
Installing Locally Developed Software
Once a package has been developed and is ready for release to the general
user community, there are some simple guidelines to follow to insure
that the software package is maintainable. The staff suggests
the following guidelines for installing locally developed software:
- RCS the source in the appropriate directory. This can be done with the ci or ci-all commands. Before RCS'ing an entire hierarchy, be sure that there are no extraneous files (i.e. object files, binaries, or other recreatable files).
- Create an empty directory in your personal hierarchy and obtain a copy of source hierarchy. This can be done with the co or co-all commands.
- Build the software package using the make command.
- If the package was built successfully, install the package using the make command.
- Distribute the software to the other systems using the rinstall command. Be sure to distribute everything that was installed (i.e. executables, libraries, man pages, documents, include files, etc.).
- If the software runs on more than one architecture, these steps must be repeated for each architecture.
- Announce the installation of the tool by posting a short news article to the appropriate news groups (i.e. cs.general, cs.gnu, etc).
Installing Software Packages
Software packages that are obtained elsewhere present some different
problems to the installer. The staff suggests the following guidelines
for installing software packages:
- RCS the original source in the appropriate directory. This can be done with the ci or ci-all commands. Before RCS'ing an entire hierarchy, be sure that there are no extraneous files (i.e. object files, binaries, or other recreatable files).
- Create an empty directory in your personal hierarchy and obtain a copy of source hierarchy. This can be done with the co or co-all commands.
- Make local changes if necessary. Build the package using the make command.
- Test the software.
Some of the following steps may seem redundant or unnecessary, but they
are necessary in order to insure that the proper source is maintained
in the source tree hierarchy.
It is of the utmost
importance that the code in the source hierarchy reflect the tools
that are installed.
- When the package is fully tested, "diff" the current source with the RCS'd source. This can be done with the rcsdiff-all command, or by checking out another copy of the source and doing a diff -r of the two directories. This step insures that any changes that may have been made to the code have not been forgotten.
- Check in any changes that were made locally.
- Create an empty directory in your personal hierarchy and obtain a copy of source hierarchy. This step insures that the software is being built with the source that has been RCS'd.
- Build the software package using the make command.
- If the package was built successfully, install the package using the make command.
- Distribute the software to the other systems using the rinstall command. Be sure to distribute everything that was installed (i.e. executables, libraries, man pages, documents, include files, etc.).
- If the software runs on more than one architecture, these steps must be repeated for each architecture.
- Announce the installation of the tool by posting a short news article to the appropriate news groups (ie cs.general, cs.gnu, etc).
Maintaining the Software
Maintaining the software falls into the same two categories as installing the
software. There is locally developed software or software packages
that are obtained elsewhere.
Maintaining Locally Developed Software
If you need to work on locally developed software that has already been
released, the staff suggests the following guidelines:
- Create an empty directory in your personal hierarchy and obtain a copy of source hierarchy. This can be done with the co or co-all commands.
- Make the changes.
- When the package is fully tested, "diff" the current source with the RCS'd source. This can be done with the rcsdiff-all command, or by checking out another copy of the source and doing a diff -r of the
two directories. This step insures that any changes that may have been made to the code have not been forgotten.
- Check in any changes that were made locally.
- Create an empty directory in your personal hierarchy and obtain a copy of source hierarchy. This step insures that the software is being built with the source that has been RCS'd.
- Build the software package using the make command.
- If the package was built successfully, install the package using the make command.
- Distribute the software to the other systems using the rinstall command. Be sure to distribute everything that was installed (ie executables, libraries, man pages, documents, include files, etc.).
- If the software runs on more than one architecture, these steps must be repeated for each architecture.
Maintaining Software Packages
Maintaining a software package falls into three categories;
1) installing local changes, 2) installing official patches,
3) installing new releases.
To make local changes or to install patches, refer to the section
for
Maintaining Locally Developed Software.
To install a new release that only contains code changes from the prior
release, the procedures outlined in the section
Maintaining Locally Developed Software
should be followed.
If the new release contains major changes such as many new files, and/or
old files that are no longer used, then the installer may want to
archive the old source to tape and follow the procedures outlined in
the section
Installing Software Packages.
Major new releases of packages should be tested in the installers personal
hierarchy before being installed in the public directories. Often
the installer will announce where the new release is to allow
users time to try it before installing it officially.
Appendix
Building a Makefile
What a Makefile Should/Should Not Contain
Each makefile should contain at a minimum the following targets:
- all
- a target which should have dependencies for building all of the required objects, binaries, libraries, etc.
- install
- a target which should place the executables, libraries, and/or man pages in the appropriate directories. The install target should not do _rinstall_'s or _rdist_'s.
- clean
- a target which should remove files built by the makefile, including any temporary files.
There should also be variables specifying the destination of
the binaries, libraries and/or man pages built by the makefile.
A Simple Sample Makefile
Below is a simple
Makefile for building and installing a command.
PROGRAM = toolname
CFLAGS = -O
DEST = /usr/grads/bin
MANDEST = /usr/grads/man/man1
all: $(PROGRAM)
$(PROGRAM):
cc $(CFLAGS) $(PROGRAM).c -o $(PROGRAM)
clean:
rm -f $(PROGRAM) a.out core *.o
install:
install -s $(PROGRAM) $(DEST)
cp $(PROGRAM).1 $(MANDEST)/.
--
KirkKelsey - 14 Feb 2006