Difference: SoftwareGuidelines (1 vs. 3)

Revision 32006-06-21 - KirkKelsey

Line: 1 to 1
Changed:
<
<
META TOPICPARENT name="KirkKelsey"
>
>
META TOPICPARENT name="SoftwareStuff"
 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.

Revision 22006-02-15 - KirkKelsey

Line: 1 to 1
 
META TOPICPARENT name="KirkKelsey"
Changed:
<
<
Below is the original guide (taken from TeX) for installing shared software on the departments 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.
>
>
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.

Changed:
<
<

Discussion

>
>

Discussion

 
Added:
>
>

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)

Line: 276 to 289
 install: install -s $(PROGRAM) $(DEST) cp $(PROGRAM).1 $(MANDEST)/.
Deleted:
<
<
 
Added:
>
>
  -- KirkKelsey - 14 Feb 2006

Revision 12006-02-14 - KirkKelsey

Line: 1 to 1
Added:
>
>
META TOPICPARENT name="KirkKelsey"
Below is the original guide (taken from TeX) for installing shared software on the departments 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

UNIX Software Installation (GUIDE 15)

<--
\tableofcontents
\listoffigures

\newpage -->

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.

<--
\newpage

\begin{figure} \input{rcsdir.tex} \caption {Incorrect and correct RCS directory hierarchy} \end{figure} -->

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.

<--
\begin{figure} [hbt]
\input{hier.tex}
\caption {Software installation directory hierarchy}
\end{figure}

\newpage -->

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)/.
<verbatim>


-- Main.KirkKelsey - 14 Feb 2006

|*META TOPICMOVED*|by="KirkKelsey" date="1139958081" from="Main.SoftwareGuidlines" to="Main.SoftwareGuidelines"|</verbatim>
<nop>
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding URCS? Send feedback