package_details.txt -- The details of a package installation. 14 June 1998 evard@mcs.anl.gov Last Updated: 17 June 1998 This document describes the exact layout and description of a software package installation. =========================================================================== 0. Overview Software is installed into its own set of directories in such a way that it doesn't overlap with any other installed software. The directories that it is installed into are referred to as its "package" directories. The pathnames of the package directories will always include the software's complete version number, ensuring that every package directory on the system is unique. Software usually has an architecture-specific component and an architecture independent component. Arch specific files including programs that have been compiled, library files, and sometimes documentation. Manual pages are considered architecture-specific because the should only be available on architectures where the software is installed. Architecture independent files often include scripts and configuration files. Every package that is installed has at lease some architecture independent files, consisting of locally-created web pages that describe that software. A package that consists entirely of scripts can be installed in an architecture independent way, so that it is automatically available on every platform that we support. However, packages that include architecture specific files will have to be re-compiled for every platform in our environment. Any package that has architecture-specific files will have at least two, and quite possible a lot more, different sets of package directories -- one for each architecture, and one for the common directory. Still, even though a software package may have more than one package directory, it is entirely contained within those package directories. =========================================================================== 1. Main directories The architecture-specific package directory of an installation is: /software///packages/ A software installation may have more than one architecture-specific package directory, or if it consists of just scripts, may not have any. The common package directory of an installation is: /software/common//packages/ Every software installation will have a common package directory, although it may be empty except for web pages. =========================================================================== 2. Subdirectories The architecture specific directories and common directory all have these subdirectories: admin - administrator created log files and the software web page bin - executables run by users lib - files referenced during run-time, including libraries man - manual page directories, containing man?? and cat?? subdirs, specifically: man1, man2, man3, man4, man5, man6, man7, man8, manl, mann cat1, cat2, cat3, cat4, cat5, cat6, cat7, cat8, catl, catn doc - documentation of various types of formats etc - executables never run by users rc - program 'resource configuration' files. Typically not used by programs but it would be nice if they all did. include - header files info - GNU style info files log - program-generated log files www - any html files The admin/ directory is intended to be used by the pkg system. All the others are intended to have files installed into them as part of the installation process. A lot of them will probably end up being empty. Some installation processes will also create other directories, which is perfectly fine. When a directory is empty after installation, it will be removed. =========================================================================== 3. Cross-links In order to make it easy to move from the arch pkg directory to the common pkg directory, we cross link them. Each architecture specific directory should have this symlink in it: common -> /software/common//packages/ The common directory should have this symlink in it: -> /software///packages/ This means that the common directory will often have multiple symlinks to architectures, one for each architecture it has been installed on. In addition, this means that architecture names and package subdirectories could possibly conflict (if, for example, some package wanted to create a "linux" subdirectory in the package installation directory). This is something to keep an eye out for, but not to be too worried about. =========================================================================== 4. Source links Also for convenience, we put links to the source in the package dirs: source -> /mcs/source// This link will break if the source is eventually tarred up. That's okay. ============================================================================ 5. Package files In the admin/ directory of the architecture specific installation, we put certain files: .notes - by hand notes arch.txt - specific notes for the user about this arch configure.out - output of the build make.out - output of the build make.install.out - output of the build configure.cf - example of an "important" file to save In addition, the admin/ directory in the common tree, will also have: pkginfo - a file created from a template index.html - the "mcs home page" for this software version If there is no architecture specific installation, then all these should be in the admin/ directory in the common tree. Depending on how the installation was done, some of these files may be missing. The two that absolutely must be there are: pkginfo index.html Templates of these are copied in or built during the installation process. ============================================================================ 6. Expected usage During the installation process, all of the directories are created, the symlinks are created, and the template files are copied in. Then the software is installed. If the software consists entirely of architecture independent scripts and data, then it should only be installed in common/, and the arch specific directory will be removed later. On the other hand, if there are arch-specific components, then the common directory should be used carefully. Only put scripts in it, or configuration files. Don't try to put manual pages there, or lib files that may or may not be architecture specific. The common directory is there to simplify things, not to save disk space. Once the software has been installed, empty directories are removed. Then, if the installer chooses, the package is installed in the larger environment by pointing symbolic links into it. For example, links from /software/common/bin may point into the common/bin directory of the package. Finally, over time, the package may be uninstalled from the larger environment by removing those symbolic links. It will still be possible for the package to exist on the file system and work correctly, because it is contained inside its own package directory. It will also be easy to remove all of its components, because they should be completely contained in the package directories.