[7] in release-74
guidelines for code submissions for the release
daemon@ATHENA.MIT.EDU (Mark Rosenstein)
Tue Apr 7 16:10:00 1992
Date: Tue, 7 Apr 92 16:07:05 -0400
From: Mark Rosenstein <mar@MIT.EDU>
To: developers@MIT.EDU, release-74@MIT.EDU
Send email to rel-eng@athena.mit.edu with:
1. the location of your code (world readable, or make
arrangements for us to be able to read it)
2. the location of the man pages
3. text for the system release notes. The user release notes
will be condensed from these.
Code should be in by the morning of Monday, 20 April 1992. If you do
not think you can make this, please talk to us now. Below is more
detail about code requirements (from the file
/source/control/doc/code-requirements).
-Mark
All submissions must follow the following rules. Submissions that do
not comply will be rejected. Release Engineering cannot afford to spend
time hand-hacking subsystems (there are about 12,000 files on each system
pack which are derived from about 500,000 source files).
1. Compilation:
Programs should compile and run on all platforms which the
new release will support.
For 7.4, the supported platforms are:
recommended test machines
-------------------------
VAX BSD 4.3 ajax.mit.edu
RT AOS 4.3 minos.mit.edu
MIPS Ultrix 4.2a paris.mit.edu
RIOS AIX 3.1 guest@tardis.mit.edu
Not required, but if possible:
SUN SunOs 4.1.2 (to be determined)
Files should be built without -g; binaries built with -g take
too much room on the packs. It is possible to debug binaries
that have been built without this extra debugging and without
too much trouble, as long as there remains an unstripped
build version in the build tree. We recommend the use of -O
to optimize the programs, but we also realize that this may
not be possible in all cases.
The supported compilers are:
VAX cc, gcc
RT cc
MIPS cc
RIOS cc
SUN gcc2, cc
gcc will be in the search path on the build machines for those
platforms for which we allow gcc (do not reference /mit/gnu/...)
2. Makefile (see alternative - #4):
all -- compile all software.
No hand configuration should need to be done by Release
Engineering; if there are differences in configurations
for each architecture, your Makefile should cope.
This should be the default rule if no make target is
specified.
install -- install software into appropriate system directories.
There should be support for an alternate root directory
specified by $(DESTDIR). $(DESTDIR) will be passed to
the top-level Makefile - it is your responsibility to
handle it appropriately in any subdirectories (it is
not automatically passed down). $(DESTDIR) symbolizes
a root (eg. /srvd). A common use would be to install
something in $(DESTDIR)/usr/athena/lib.
The install process must be thorough and re-entrant.
The install process must create any subdirectories
beyond the standard directories (eg. /usr/athena/lib
will exist, but do not rely on /usr/athena/lib/zephyr
existing). It must also install any documentation
associated with the project. The install process
should not die if it is invoked a second time - it
is common to re-install a package because bugs had
to be fixed during testing.
Binaries should be installed stripped. Do not strip
the binaries in the build tree; these may later be
needed for debugging.
A good way of testing "make install" is to create a
directory hierarchy under /tmp and then try installing
into it. To do this, type:
mkdir /tmp/usr/athena/{bin,include,lib,etc,man} \
/tmp/{bin,etc}/athena /tmp/usr/lib/lint
make install DESTDIR=/tmp
clean -- delete compiled executables, intermediate object files,
editor backup files, and all other files that were
generated during the build.
depend -- this rule should edit the Makefiles and add source
dependencies. Your Makefile should at least not produce
an error if called with "make depend"; you may opt to
use an empty depend rule and not actually do any
Makefile editing.
Certain other arrangements can be made. For example, there are
Makefiles that use the "world" construct instead of the "all"
construct. However, we will not do multi-pass builds or
multi-pass installs, or any other type of work that requires
hand intervention. As previously stated, there are far too
many items in the release to provide special procedures to deal
with any single package.
3. Documentation:
Manual pages should accompany all user programs that are installed
in the release. It is recommended that you have them proofread
by someone else, preferrably in the Documentation group.
Release notes submissions should be sent to <rel-eng@MIT.EDU>
and should contain the text of what you wish to appear in the
release notes. It should be a fairly accurate list, as this
is for the technical release notes (the user release notes
are a condensed version of these notes tailored to the standard
users; however, we do wish to make the technical details
available on-line to those interested).
4. Imake support (Makefile alternative)
We encourage user to simply make Imakefiles for the building
and installation of programs. A sample Imakefile can be found
in /source/control/doc/sample.Imakefile.
Various target directories vary depending on the platform and
the compiler flags also vary, thus making the writing of
Makefiles rather complex. On the new architectures, one
requires the use of -I and -L to find the Athena include and
library files.
Hints on creating an Imakefile using our standard rules:
- Various Makefile variables are defined for your benefit.
Shown below are some of the definitions and their values on
most of the platforms (the values do vary for each platform):
ATHBINDIR User programs (/usr/athena/bin)
ATHCONFDIR Configuration files (/etc/athena)
ATHETCDIR Misc. utilities/daemons (/usr/athena/etc)
ATHINCDIR Include files (/usr/athena/include)
ATHLIBDIR Library files (/usr/athena/lib)
ATHMANDIR Manual pages (/usr/athena/man)
ATHRBINDIR Programs that must be on the root (/bin/athena)
ATHRETCDIR Daemons that must be on the root (/etc/athena)
ATHXAPPDIR X Applications Default directory
ATHXBITDIR X Bitmap directory
ATHXINCDIR X Includes directory
ATHXLIBDIR X Libraries directory
RM The name of remove command (rm -f)
INSTALL The name of the install procedure (install -c)
CC The default C compiler (cc)
- The available rules are defined in /source/config/Imake.rules.
A summary is listed at the top of this file. All of the
imake configuration templates can be located in /source/config/.
- If additional flags are needed for your project to compile,
set DEFINES - CFLAGS includes $(DEFINES). Do not set CFLAGS
directly as this also includes many of the OS specific flags,
such as the include paths. To change the debugging flags
that the project is compiled with, set CDEBUG (the default
is to use optimizations). For example:
#ifdef ibm032
CDEBUG= /* -O breaks on xyz.c on the RT */
#endif
DEFINES= -DCONFFILE=\"$(ATHCONFDIR)/xyz.conf\"
- To traverse into subdirectories, simply #define SUBDIRS or
ISUBDIRS. ISUBDIRS is a list of subdirectories for which
there are also Imakefiles. SUBDIRS is a list of
subdirectories for which there are only Makefiles. If you
are using Makefiles only, the subdirectories must also
include rules for all,depend,clean,install (they may be
empty rules).
- The following are the pre-processor flags that are defined on
each architecture during the parsing of the Imakefiles.
Additional flags that should not be generally be used in
conditionals in your Imakefiles are listed in parentheses.
vax vax
rt ibm032
mips mips, ultrix, ULTRIX40
rios _AIX, _IBMR2, AIXV=31, SYSV (ibm,aix)
sun [to be determined]
The following will be defined automatically when compiling
C programs (some of these are defined in the global imake
template). Additional flags that should not be used in
your conditionals are listed in parentheses.
vax vax
rt ibm032
mips mips, ultrix, ULTRIX40
rios _AIX, _IBMR2, AIXV=31, POSIX
(_BSD, _BSD_INCLUDES, _POSIX_SOURCE)
sun [to be determined]
N.B.:
1. The only reason we do not recommend the use of
_POSIX_SOURCE is that many of the operating systems,
when put into strict POSIX mode may have internal
inconsistencies in the system header files and reduce
the functionality of the development environment. To
accomodate POSIX systems, we will be defining POSIX
on all systems where POSIX is the preferred style of
programming.
- To test your Imakefiles and general rules, simply do:
[cd to the top-level of your project]
set path=(/afs/rel-eng/system/config/$bindir $path)
xmkmf /source
This will create a Makefile from your top-level Imakefile.
Then you may proceed to build all the other Makefiles by
issuing the command:
make Makefiles
After this, you should be able to use the standard rules,
such as all, depend, clean, install.
- WARNINGS:
1. Spaces are sometimes significant in the rules. A
common mistake is to put a space between the comma and the
install directory. The C pre-processor used to parse the
Imakefiles considers the space as part of the string, which
may cause problems when other data has to be concatenated
at the beginning of those strings.
2. Avoid having an ISUBDIRS or SUBDIRS definition beginning
with "include"; many versions of "make" treat this as a
special keyword, and the current set of rules will cause
this to break. (No clean fix is yet known.)
***********************************************************************
People working on modules from elsewhere should do the following things
when 15% or more of the code is altered.
(This is a general rule-of-thumb, as was presented by Dan Geer in 1986)
***********************************************************************
5. RCS macros:
/*
* $Id$
*/
#ifndef lint
static char rcsid[] = "$Header$";
#endif lint
6. Copyright notices:
/* Copyright 1992 by the Massachusetts Institute of Technology.
* For copying and distribution information, see the file
* "mit-copyright.h".
*/
#include "mit-copyright.h"
