for review: WWW changes
Peter David ROSS
petdr at cs.mu.OZ.AU
Fri Sep 4 15:00:54 AEST 1998
Hi,
Tyson here is some more stuff for you to cast your eye over.
I have already checked this in.
Pete.
===================================================================
Estimated hours taken: 4
More support for installing the web site automatically.
Makefile.common:
Ensure that the premissions on the installed web site are world
readable.
information/Makefile:
Make the text file versions of the compiler/notes directory.
Ensure that the premissions on the installed web site are world
readable.
information/include/developer.inc:
Add the correct path to all the developer documents.
mailing-lists/archive2html.sh:
Make sure that the email messages are formatted in a monospace font
which displays the tabs.
mailing-lists/rearchive:
Script which keeps updates the archive for the current month.
mailing-lists/create_archive:
Script which will create the entire mailing list archive.
mailing-lists/mercury-developers/Makefile:
mailing-lists/mercury-users/Makefile:
Ensure that the premissions on the installed web site are world
readable.
information/developers/bytecode.html:
information/developers/c_coding_standard.html:
information/developers/remote_cvs.html:
Add some files that I forgot to include.
Index: Makefile.common
===================================================================
RCS file: /home/staff/zs/imp/w3/Makefile.common,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 Makefile.common
--- Makefile.common 1998/09/01 02:41:02 1.1.1.1
+++ Makefile.common 1998/09/04 02:23:56
@@ -30,6 +30,7 @@
cd $$dir; $(MAKE) install); \
done
endif
+ chmod a+r $(INSTALL_WEBDIR)/*
.PHONY: clean
clean:
Index: information/Makefile
===================================================================
RCS file: /home/staff/zs/imp/w3/information/Makefile,v
retrieving revision 1.2
diff -u -r1.2 Makefile
--- Makefile 1998/09/03 06:36:05 1.2
+++ Makefile 1998/09/04 04:37:34
@@ -21,15 +21,18 @@
cvs checkout mercury/library; \
cvs checkout mercury/compiler/notes)
echo "LIBRARY_DIR=`pwd`/mercury/library" > mercury/Mmake.common
+ (cd mercury/compiler/notes; mmake)
(cd mercury/doc; mmake library-chapters.texi split_html ps)
+ cp -a mercury/compiler/notes/*.text doc
cp -a mercury/doc/*.html mercury/compiler/notes/*.html doc
cp -a mercury/doc/*.ps doc
(cd doc; gzip -f -9 *.ps)
local_install: target
- for dir in bench doc papers; \
- do \
- cp -a $$dir $(INSTALL_WEBDIR); \
+ for dir in bench developers doc papers; \
+ do \
+ cp -a $$dir $(INSTALL_WEBDIR); \
+ chmod -R a+r $(INSTALL_WEBDIR)/$$dir; \
done
local_clean:
Index: information/include/developer.inc
===================================================================
RCS file: /home/staff/zs/imp/w3/information/include/developer.inc,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 developer.inc
--- developer.inc 1998/09/01 02:41:11 1.1.1.1
+++ developer.inc 1998/09/04 02:45:16
@@ -13,79 +13,79 @@
The standard used for the C source in the Mercury compiler. <p>
Available in
- <a href="c_coding_standard.html">HTML</a>
+ <a href="developers/c_coding_standard.html">HTML</a>
<p>
<li> <strong>Reviews</strong> <br>
Outlines reviewing procedure. <p>
Available in
- <a href="reviews.html">HTML</a> and
- <a href="reviews.text">Plain text</a>
+ <a href="doc/reviews.html">HTML</a> and
+ <a href="doc/reviews.text">Plain text</a>
<p>
<li> <strong>Mercury Coding Standards</strong> <br>
Standard for Mercury code. <p>
Available in
- <a href="coding_standards.html">HTML</a> and
- <a href="coding_standards.text">Plain text</a>
+ <a href="doc/coding_standards.html">HTML</a> and
+ <a href="doc/coding_standards.text">Plain text</a>
<p>
<li> <strong>Compiler Design</strong> <br>
Details of the compiler design. <p>
Available in
- <a href="compiler_design.html">HTML</a> and
- <a href="compiler_design.text">Plain text</a>
+ <a href="doc/compiler_design.html">HTML</a> and
+ <a href="doc/compiler_design.text">Plain text</a>
<p>
<li> <strong>Allocation</strong> <br>
Details of the allocation scheme currently being implemented. <p>
Available in
- <a href="allocation.html">HTML</a> and
- <a href="allocation.text">Plain text</a>
+ <a href="doc/allocation.html">HTML</a> and
+ <a href="doc/allocation.text">Plain text</a>
<p>
<li> <strong>Module system</strong> <br>
Details of the module system. <p>
Available in
- <a href="module_system.html">HTML</a> and
- <a href="module_system.text">Plain text</a>
+ <a href="doc/module_system.html">HTML</a> and
+ <a href="doc/module_system.text">Plain text</a>
<p>
<li> <strong>Release checklist</strong> <br>
The release procedure. <p>
Available in
- <a href="release_checklist.html">HTML</a> and
- <a href="release_checklist.text">Plain text</a>
+ <a href="doc/release_checklist.html">HTML</a> and
+ <a href="doc/release_checklist.text">Plain text</a>
<p>
<li> <strong>Garbage collection and C code</strong> <br>
<p>
Available in
- <a href="gc_and_c_code.html">HTML</a> and
- <a href="gc_and_c_code.text">Plain text</a>
+ <a href="doc/gc_and_c_code.html">HTML</a> and
+ <a href="doc/gc_and_c_code.text">Plain text</a>
<p>
<li> <strong>Glossary</strong> <br>
Terms used in the Mercury implementation. <p>
Available in
- <a href="glossary.html">HTML</a> and
- <a href="glossary.text">Plain text</a>
+ <a href="doc/glossary.html">HTML</a> and
+ <a href="doc/glossary.text">Plain text</a>
<p>
<li> <strong>To do list</strong> <br>
Things still to do in the Mercury project. <p>
Available in
- <a href="todo.html">HTML</a> and
- <a href="todo.text">Plain text</a>
+ <a href="doc/todo.html">HTML</a> and
+ <a href="doc/todo.text">Plain text</a>
<p>
<!---------
@@ -94,7 +94,7 @@
Information on the Mercury bytecode. <p>
Available in
- <a href="bytecode.html">HTML</a>
+ <a href="developers/bytecode.html">HTML</a>
<p>
-------->
Index: mailing-lists/archive2html.sh
===================================================================
RCS file: /home/staff/zs/imp/w3/mailing-lists/archive2html.sh,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 archive2html.sh
--- archive2html.sh 1998/09/01 02:41:02 1.1.1.1
+++ archive2html.sh 1998/09/04 02:17:06
@@ -1,7 +1,14 @@
#!/bin/sh
#
+# Create one hypermail archive for the month and mailing list specified.
+# This command must be run in the directory this script is located in.
+#
usage="archive2html.sh -y <year> -m <month> -f <filename> -d <directory>"
+ # Shows the messages inside <pre> </pre> tags so we don't lose
+ # formatting.
+export HM_SHOWHTML=0
+
while getopts ad:f:m:uy: flag ; do
case $flag in
a) archive=true ;;
@@ -44,7 +51,3 @@
esac
hypermail -x -m $filename -a "../../mailing-lists.html" -l "$file $month $year"
-
-# if [ $archive = "true" ]
-# then
-# fi
Index: mailing-lists/rearchive
===================================================================
RCS file: /home/staff/zs/imp/w3/mailing-lists/rearchive,v
retrieving revision 1.1
diff -u -r1.1 rearchive
--- rearchive 1998/09/03 06:36:13 1.1
+++ rearchive 1998/09/04 02:17:30
@@ -1,5 +1,10 @@
#!/bin/sh
+#
+# Update the mailing list archive. Should be run every day.
+# This command must be run in the current directory.
+#
+set -x
dir=/home/mercury/public/mailing_lists/
day=`date '+%d'`
Index: mailing-lists/mercury-developers/Makefile
===================================================================
RCS file: /home/staff/zs/imp/w3/mailing-lists/mercury-developers/Makefile,v
retrieving revision 1.2
diff -u -r1.2 Makefile
--- Makefile 1998/09/03 06:36:18 1.2
+++ Makefile 1998/09/04 02:28:50
@@ -16,5 +16,6 @@
cp -a $$dir $(INSTALL_WEBDIR); \
fi \
done
+ chmod -R a+r $(INSTALL_WEBDIR)*
include ../../Makefile.common
Index: mailing-lists/mercury-users/Makefile
===================================================================
RCS file: /home/staff/zs/imp/w3/mailing-lists/mercury-users/Makefile,v
retrieving revision 1.2
diff -u -r1.2 Makefile
--- Makefile 1998/09/03 06:36:26 1.2
+++ Makefile 1998/09/04 02:29:10
@@ -14,6 +14,7 @@
cp -a $$dir $(INSTALL_WEBDIR); \
fi \
done
+ chmod -R a+r $(INSTALL_WEBDIR)/*
list.html: touch
New File: information/developers/bytecode.html
===================================================================
<html>
<head>
<title>
Information On The Mercury Bytecode Format
</title>
</head>
<body
bgcolor="#ffffff"
text="#000000"
>
<hr>
<!-------------------------->
<h1>
Information On The Mercury Bytecode Format</h1>
<hr>
<!-------------------------->
<h2> Summary of types </h2>
<dl>
<dt> byte
<dd>
unsigned char 0-255
<dt> cstring
<dd>
Sequence of non-zero bytes terminated by zero-byte. <br>
XXX: May change this later to allow embedded
zero-bytes in strings.
<dt> short
<dd>
2 bytes interpreted as signed short.
It is 2's complement and big-endian. (The
most significant byte is read first.)
<dt> int
<dd>
4 bytes interpreted as a signed int.
It is 2's complement and big-endian.
<dt> float
<dd>
8 bytes interpreted as floating point value.
It is IEEE-754 64-bit format and big-endian.
<dt> list of T
<dd>
contiguous sequence of T
<dt> determinism
<dd>
one byte interpreted as follows
<ul>
<li> 0 = det
<li> 1 = semidet
<li> 2 = multidet
<li> 3 = nondet
<li> 4 = cc_multidet
<li> 5 = cc_nondet
<li> 6 = erroneous
<li> 7 = failure
</ul>
<dt> tag is one of
<dd>
<ul>
<li> 0 (byte) (simple tag) followed by
<ul>
<li> primary (byte)
</ul>
<li> 1 (byte) (complicated tag) followed by
<ul>
<li> primary (byte)
<li> secondary (int)
</ul>
<li> 2 (byte) (complicated constant tag) followed by
<ul>
<li> primary (byte)
<li> secondary (int)
</ul>
<li> 3 (byte) (enum tag)
(For enumeration of pure constants.)
<li> 4 (byte) (no_tag)
</ul>
XXX: Need explanation of all these.
<dt> cons_id (constructor id) is one of:
<dd>
<ul>
<li> 0 (byte) (cons) followed by
<ul>
<li> functor name (cstring)
<li> arity (short)
<li> tag (tag)
</ul>
<li> 1 (byte) (int const) followed by
<ul>
<li> integer constant (int)
</ul>
<li> 2 (byte) (string const) followed by
<ul>
<li> string constant (cstring) <br>
XXX: no '\0' in strings!
</ul>
<li> 3 (byte) (float const) followed by
<ul>
<li> float constant (float)
</ul>
<li> 4 (byte) (pred const) followed by
<ul>
<li> module id (cstring)
<li> predicate id (cstring)
<li> arity (short)
<li> procedure id (byte)
</ul>
<li> 5 (byte) (code addr const) followed by
<ul>
<li> module id (cstring)
<li> predicate id (cstring)
<li> arity (short)
<li> procedure id (byte)
</ul>
<li> 6 (byte) (base type info const) followed by
<ul>
<li> module id (cstring)
<li> type name (cstring)
<li> type arity (byte)
</ul>
</ul>
Note that not all of these alternatives are
meaningful in all bytecodes that have arguments of
type cons_id. <br>
XXX: Specify exactly which cases are meaningful.
<dt> op_arg (argument to an operator) is one of:
<dd>
<ul>
<li> 0 (byte) followed by
<ul>
<li> variable slot (short)
</ul>
<li> 1 (byte) followed by
<ul>
<li> integer constant (int)
</ul>
<li> 2 (byte) followed by
<ul>
<li> float constant (float) XXX: not yet supported
</ul>
</ul>
<dt> dir (direction of information movement in general unification)
is one of:
<dd>
<ul>
<li> 0 (byte) to_arg
<li> 1 (byte) to_var
<li> 2 (byte) to_none
</ul>
</dl>
<h2> Summary of Bytecodes </h2>
<p>
Note: Currently we specify only the static layout of bytecodes.
We also need to specify the operational semantics of the bytecodes,
which can be done by specifying state transitions on the abstract
machine. That is, to specify the meaning of a bytecode, we simply
say how the state of the abstract machine has changed from before
interpreting the bytecode to after interpreting the bytecode.
<p>
<ul>
<li> enter_pred (0)
<ul>
<li> predicate name (cstring)
<li> number of procedures in predicate (short)
</ul>
<li> endof_pred (1)
<li> enter_proc (2)
<ul>
<li> procedure id (byte) <br>
procedure id is used to distinguish the procedures
in a predicate. <br>
XXX: should use short instead?
<li> determinism of the procedure (determinism)
<li> label count (short) <br>
Number of labels in the procedure. Used for allocating a
table of labels in the interpreter.
<li> temp count (short) <br>
Number of temporary variables needed for this procedure. (?)
<li> length of list (short) <br>
Number of items in next arg
<li> list of
<ul>
<li> Variable info (cstring)
</ul>
XXX: we should also have typeinfo for each variable.
</ul>
<li> endof_proc (3)
<li> label (4)
<ul>
<li> Code label. (short)
</ul>
Used for jumps, switches, if-then-else, etc.
<li> enter_disjunction (5)
<ul>
- label id (short) <br>
Label refers to the label immediately after the disjunction.
</ul>
<li> endof_disjunction (6)
<li> enter_disjunct (7)
<ul>
<li> label id (short) <br>
Label refers to label for next disjunct.
</ul>
<li> endof_disjunct (8)
<ul>
<li> label id (short) <br>
Label refers to label for next disjunct.(?)
Is -1 if there is no next disjunct in this disjunction.
</ul>
<li> enter_switch (9)
<ul>
<li> variable in slots on which we are switching (short)
<li> label immediately after the switch (short)
</ul>
We jump to the label after we've performed the switch.
label refers to label immediately after corresponding
endof_switch.
<li> endof_switch (10)
<li> enter_switch_arm (11)
<ul>
<li> constructor id (cons_id)
<li> label id (short) <br>
label refers to label for next switch arm.
</ul>
<li> endof_switch_arm (12)
<ul>
<li> label id (short)
Label id refers to label immediately before next switch arm.
(?)
</ul>
<li> enter_if (13)
<ul>
<li> else label id (short)
<li> follow label id (short) <br>
label refers to label at endof_if
Note that we must've pushed a failure context
before entering the enter_if. If the condition
fails, we follow the failure context.
<li> frame pointer tmp (short) <br>
XXX: hmm... dunno..
</ul>
<li> enter_then (14)
<ul>
<li> frame pointer temp (short) <br>
XXX: what's this for?
</ul>
XXX: should have flag here? [I wrote this note in a meeting.
What in hell did I mean?]
<li> endof_then (15) XXX: enter_else is a better name.
<ul>
<li> follow label (short) <br>
XXX: label just before endof_if ???
</ul>
<li> endof_if (16)
<li> enter_negation (17)
<ul>
<li> label id (short)
</ul>
label refers to label at endof_negation.
Note: As with if-then-else, we must push a failure
context just before entering enter_negation. If the
negation fails, we follow the failure context.
<li> endof_negation (18)
<li> enter_commit (19)
<ul>
- temp (short) <br>
XXX: what's this for?
</ul>
XXX: how does this work?
<li> endof_commit (20)
<ul>
<li> temp (short) <br>
XXX: what's this for?
</ul>
<li> assign (21)
<ul>
<li> Variable A in slots (short)
<li> Variable B in slots (short)
</ul>
A := B. Copy contents of slot B to slot A.
<li> test (22)
<ul>
<li> Variable A in slots (short)
<li> Variable B in slots (short)
</ul>
Used to test atomic values (int, float, etc). Before entering
test, a failure context must be pushed. If the test fails,
the failure context is followed.
<li> construct (23)
<ul>
<li> variable slot (short)
<li> constructor id (cons_id)
<li> list length of next arg (short)
<li> list of:
<ul>
<li> variable slot (short)
</ul>
</ul>
Apply constructor to list of arguments (in list of variable slots)
and store result in a variable slot.
<li> deconstruct (24)
<ul>
<li> variable slot Var (short)
<li> constructor id (cons_id)
<li> list length of next arg (short)
<li> list of:
<ul>
<li> variable slot (short)
</ul>
</ul>
<p>
If cons_id is:
<dl>
<dt> a functor applied to some args,
<dd>
then remove functor and put args into variable slots.
<dt> an integer constant,
<dd>
then check for equality of the constant and the
value in the variable slot
<dt> a float constant,
<dd>
then check for equality of the constant and the
value in the variable slot.
<dt> anything else,
<dd>
then makes no sense and interpreter should
raise error. <br>
XXX: correct?
</dl>
<p>
Note: We must push a failure context before entering deconstruct. If the deconstruct fails (i.e. functor of Var isn't
the same as cons_id, or ints are not equal, or floats are
not equal), then we must follow the failure context.
<li> complex_construct (25)
<ul>
<li> var (short)
<li> cons id (cons_id)
<li> list length (short)
<li> list of:
<ul>
<li> var (short)
<li> direction (dir)
</ul>
</ul>
This used for general unification using partially instantiated
terms. This is made possible by bromage's aliasing work.
<li> complex_deconstruct (26)
<ul>
<li> variable slot (short)
<li> constructor id (cons_id)
<li> list length of next arg (short)
<li> list of
<ul>
<li> variable slot (short)
<li> direction (dir)
</ul>
</ul>
Note: This is a generalised deconstruct. The directions specify
which way bindings move. XXX: This is still not 100% crystal clear.
<li> place_arg (27)
<ul>
<li> register number (byte) <br>
XXX: Do we have at most 256 registers?
<li> variable number (short)
</ul>
Move number from variable slot to register.
(Note: See notes for pickup_arg.) <p>
XXX: We will need to #include imp.h from ther Mercury runtime,
since this specifies the usage of registers. For example, we
need to know whether we're using the compact or non-compact
register allocation method for parameter passing. (The compact
method reuses input registers as output registers. In the
non-compact mode, input and output registers are distinct.)
<li> pickup_arg (28)
<ul>
<li> register number (byte)
<li> variable number in variable slots (short)
</ul>
Move argument from register to variable slot. <p>
(Note: We currently don't make use of floating-point registers.
The datatype for pickup_arg in the bytecode generator allows
for distinguishing register `types', that is floating-point
register or normal registers. We may later want to spit out
another byte `r' or `f' to identify the type of register.)
<li> call (29)
<ul>
<li> module id (cstring)
<li> predicate id (cstring)
<li> arity (short)
<li> procedure id (byte)
</ul>
XXX: If we call a Mercury builtin, the module name is `mercury_builtin'.
What if the user has a module called mercury_builtin?
<li> higher_order_call (30)
<ul>
<li> var (short)
<li> input variable count (short)
<li> output variable count (short)
<li> determinism (determinism)
</ul>
<li> builtin_binop (31)
<ul>
<li> binary operator (byte) <br>
This single byte is an index into a table of binary
operators.
<li> argument to binary operator (op_arg)
<li> another argument to binary operator (op_arg)
<li> variable slot which receives result of binary operation (short)
</ul>
XXX: Floating point operations must be distinguished from
int operations. In the interpreter, we should use a lookup table
that maps bytes to the operations.
<li> builtin_unop (32)
<ul>
<li> unary operator (byte)
An index into a table of unary operators.
<li> argument to unary operator (op_arg)
<li> variable slot which receives result of unary operation (short)
</ul>
<li> builtin_bintest (33)
<ul>
<li> binary operator (byte)
An index into a table of binary operators.
<li> argument to binary test (op_arg)
<li> another argument to binary test op_arg)
</ul>
Note we must first push a choice point which we may follow should
the test fail.
<li> builtin_untest (34)
<ul>
<li> unary operator (byte)
An index into a tabler of unary operators.
<li> argument to unary operator (op_arg)
</ul>
Note we must first push a choice point which we may follow should
the test fail.
<li> semidet_succeed (35)
<li> semidet_success_check (36)
<li> fail (37)
<li> context (38)
<ul>
<li> line number in Mercury source that the current bytecode
line corresponds to. (short)
</ul>
XXX: Still not clear how we should implement `step' in a debugger
since a single context may have other contexts interleaved in it.
<li> not_supported (39)
<p>
Some unsupported feature is used. Inline C in Mercury code,
for instance. Any procedure thatr contains inline C
(or is compiled Mercury?) must have the format:
<ul>
<li> enter_pred ...
<li> not_supported
<li> endof_pred
</ul>
</ul>
<hr>
<!-------------------------->
Comments? Mail <a href = "mailto:mercury at cs.mu.oz.au">mercury at cs.mu.oz.au</a>,
or see our <a href = "../email.html" >contact</a> page.<br>
Last update was $Date: 1997/04/22 01:25:56 $ by $Author: trd $@cs.mu.oz.au. <br>
</body>
</html>
New File: information/developers/c_coding_standard.html
===================================================================
<html>
<head>
<title>
C Coding Standard for the Mercury Project
</title>
</head>
<body
bgcolor="#ffffff"
text="#000000"
>
<hr>
<!-------------------------->
<h1>
C Coding Standard for the Mercury Project</h1>
<hr>
<!-------------------------->
These coding guidelines are presented in the briefest manner possible
and therefore do not include rationales. <p>
Because the coding standard has been kept deliberately brief, there are
some items missing that would be included in a more comprehensive
standard. For more on commonsense C programming,
consult the <a href="ftp://ftp.cs.toronto.edu/doc/programming/ihstyle.ps">
Indian Hill C coding standard </a> or the
<a href="http://www.eskimo.com/~scs/C-faq/top.html">
comp.lang.c FAQ</a>. <p>
<h2>
1. File organization</h2>
<h3>
1.1. Modules and interfaces</h3>
We impose a discipline on C to allow us to emulate (poorly) the modules
of languages such as Ada and Modula-3.
<ul>
<li> Every .c file has a corresponding .h file with the
same basename. For example, list.c and list.h.
<li> We consider the .c file to be the module's implementation
and the .h file to be the module's interface. We'll
just use the terms `source file' and `header'.
<li> All items exported from a source file must be declared in
the header. These items include functions, variables, #defines,
typedefs, enums, structs, and so on. In short, an item is anything
that doesn't allocate storage.
Qualify function prototypes with the `extern' keyword.
Also, do qualify each variable declaration
with the `extern' keyword, otherwise storage for the
variable will be allocated in every source file that
includes the header containing the variable definition.
<li> We import a module by including its header.
Never give extern declarations for imported
functions in source files. Always include the header of the
module instead.
<li> Each header must #include any other headers on which it depends.
Hence it's imperative every header be protected against multiple
inclusion. Also, take care to avoid circular dependencies.
<li> Always include system headers using the angle brackets syntax, rather
than double quotes. That is
<font color="#0000ff"><tt>#include <stdio.h></tt>
<font color="#000000">.
Mercury-specific headers should be included using the double
quotes syntax. That is
<font color="#0000ff"><tt>#include "mercury_module.h"</tt>
<font color="#000000">
Do not put root-relative or `..'-relative directories in
#includes.
</ul>
<h3>
1.2. Organization within a file</h3>
<h4>
1.2.1. Source files</h4>
Items in source files should be in this order:
<ul>
<li> Prologue comment describing the module.
<li> #includes of system headers (such as stdio.h and unistd.h)
<li> #includes of headers specific to this project. But note that
for technical reasons,
<font color="#0000ff">mercury_imp.h<font color=#000000">
must be the first #include.
<li> Any local #defines.
<li> Definitions of any local (that is, file-static) global variables.
<li> Prototypes for any local (that is, file-static) functions.
<li> Definitions of functions.
</ul>
<h4>
1.2.2. Header files</h4>
Items in headers should be in this order:
<ul>
<li> #defines
<li> typedefs, structs, unions, enums
<li> extern variable declarations
<li> function prototypes
</ul>
Note also that every header should be protected against multiple inclusion
using the following idiom:
<font color="#0000ff">
<pre>
#ifndef MODULE_H
#define MODULE_H
/* body of module.h */
#endif /* not MODULE_H */
</pre>
<font color="#000000">
<h2>
2. Comments</h2>
<h3>
2.1. What should be commented</h3>
<h4>
2.1.1. Functions</h4>
Each function should have a one-line description of what it does.
Additionally, both the inputs and outputs (including pass-by-pointer)
should be described. Any side-effects not passing through the explicit
inputs and outputs should be described. If any memory is allocated,
you should describe who is responsible for deallocation.
If memory can change upon successive invocations (such as function-static
data), mention it. If memory should not be deallocated by anyone
(such as constant string literals), mention this.
<p>
Note: memory allocation for C code that must interface
with Mercury code or the Mercury runtime should be
done according to the documentation in mercury/runtime/heap.h
and the Mercury User's Guide and Mercury Language Reference Manual.
<font color="#ff0000">
XXX: Currently none of these say anything about it, though.
<font color="#000000">
<h4>
2.1.2. Headers</h4>
Such function comments should be present in header files for each function
exported from a source file. Ideally, a client of the module should
not have to look at the implementation, only the interface.
In C terminology, the header should suffice for
working out how an exported function works.
<h4>
2.1.3. Source files</h4>
Every source file should have a prologue comment which includes:
<ul>
<li> Copyright notice.
<li> GNU Public Licence info.
<li> Short description of the purpose of the module.
<li> Any design information or other details required to understand
and maintain the module.
</ul>
<h4>
2.1.4. Global variables</h4>
Any global variable should be excruciatingly documented. This is
especially true when globals are exported from a module.
In general, there are very few circumstances that justify use of
a global.
<h3>
2.1. Comment style</h3>
Use comments of this form:
<font color="#0000ff">
<pre>
/*
** Here is a comment.
** And here's some more comment.
*/
</pre>
<font color="#000000">
For annotations to a single line of code:
<font color="#0000ff">
<pre>
i += 3; /* Here's a comment about this line of code. */
</pre>
<font color="#000000">
<h3>
2.2. Guidelines for comments</h3>
<h3>
2.3. Revisits</h3>
Any code that needs to be revisited because it is a temporary hack
(or some other expediency) must have a comment of the form:
<font color="#0000ff">
<pre>
/*
** XXX: <reason for revisit>
*/
</pre>
<font color="#000000">
The <reason for revisit> should explain the problem in a way
that can be understood by developers other than the author of the
comment.
<h3>
2.4. Comments on preprocessor statements</h3>
The <tt>#ifdef</tt> constructs should
be commented like so if they extend for more than a few lines of code:
<font color="#0000ff">
<pre>
#ifdef SOME_VAR
/*...*/
#else /* not SOME_VAR */
/*...*/
#endif /* not SOME_VAR */
</pre>
<font color="#000000">
Similarly for
<font color="#0000ff"><tt>#ifndef</tt><font color="#000000">.
<p>
Use the GNU convention of comments that indicate whether the variable
is true in the #if and #else parts of an #ifdef or #ifndef. For
instance:
<font color="#0000ff">
<pre>
#ifdef SOME_VAR
#endif /* SOME_VAR */
#ifdef SOME_VAR
/*...*/
#else /* not SOME_VAR */
/*...*/
#endif /* not SOME_VAR */
#ifndef SOME_VAR
/*...*/
#else /* SOME_VAR */
/*...*/
#endif /* SOME_VAR */
</pre>
<font color="#000000">
<h2>
3. Declarations</h2>
<h3>
3.1. Pointer declarations</h3>
Attach the pointer qualifier to the variable name.
<font color="#0000ff">
<pre>
char *str1, *str2;
</pre>
<font color="#000000">
<h3>
3.2. Static and extern declarations</h3>
Limit module exports to the absolute essentials. Make as much static
(that is, local) as possible since this keeps interfaces to modules simpler.
<h3>
3.3. Typedefs</h3>
Use typedefs to make code self-documenting. They are especially
useful on structs, unions, and enums.
<h2>
4. Naming conventions</h2>
<h3>
4.1. Function and variable names</h3>
Use all lowercase with underscores to separate words.
For instance, <tt>soul_machine</tt>.
<h3>
4.2. Enums, macros and #define constants</h3>
Use all uppercase with underscores to separate words.
For instance, <tt>MAX_HEADROOM</tt>.
<h3>
4.3. Typedefs</h3>
Use first letter uppercase for each word, other letters lowercase and
underscores to separate words.
For instance, <tt>Directory_Entry</tt>.
<h3>
4.4. Mercury specifics </h3>
For anything exported from mercury/runtime, prefix it with MR_.
For anything exported from mercury/library, prefix it with ML_.
<h2>
5. Syntax and layout</h2>
<h3>
5.1. Minutiae</h3>
Use 8 spaces to a tab. No line should be longer than 79 characters.
If a statement is too long, continue it on the next line <em>indented
two levels deeper</em>. If the statement extends over more than two
lines, then make sure the subsequent lines are indented to the
same depth as the second line. For example:
<font color="#0000ff">
<pre>
here = is_a_really_long_statement_that_does_not_fit +
on_one_line + in_fact_it_doesnt_even_fit +
on_two_lines;
if (this_is_a_somewhat_long_conditional_test(
in_the_condition_of_an +
if_then))
{
/*...*/
}
</pre>
<font color="#000000">
<h3>
5.2. Statements</h3>
Use one statement per line.
Here are example layout styles for the various syntactic constructs:
<h4>
5.2.1. If statement</h4>
Use the "/* end if */" comment if the if statement is larger than a page.
<font color="#0000ff">
<pre>
/*
** Curlies are placed in a K&R-ish manner.
** And comments look like this.
*/
if (blah) {
/* Always use curlies, even when there's only
** one statement in the block.
*/
} else {
/* ... */
} /* end if */
/*
** if the condition is so long that the open curly doesn't
** fit on the same line as the `if', put it on a line of
** its own
*/
if (a_very_long_condition() &&
another_long_condition_that_forces_a_line_wrap())
{
/* ... */
}
</pre>
<font color="#000000">
<h4>
5.2.2. Functions</h4>
Function names are flush against the left margin. This makes it
easier to grep for function definitions (as opposed to their invocations).
In argument lists, put space after commas. And use the <tt>/* func */</tt>
comment when the function is longer than a page.
<font color="#0000ff">
<pre>
int
rhododendron(int a, float b, double c) {
/* ... */
} /* end rhododendron() */
</pre>
<font color="#000000">
<h4>
5.2.3. Variables</h4>
Variable declarations shouldn't be flush left, however.
<font color="#0000ff">
<pre>
int x = 0, y = 3, z;
int a[] = {
1,2,3,4,5
};
</pre>
<font color="#000000">
<h4>
5.2.4. Switches </h4>
<font color="#0000ff">
<pre>
switch (blah) {
case BLAH1:
/*...*/
break;
case BLAH2: {
int i;
/*...*/
break;
}
default:
/*...*/
break;
} /* switch */
</pre>
<font color="#000000">
<h4>
5.2.5. Structs, unions, and enums </h4>
<font color="#0000ff">
<pre>
struct Point {
int tag;
union cool {
int ival;
double dval;
} cool;
};
enum Stuff {
STUFF_A, STUFF_B /*...*/
};
</pre>
<font color="#000000">
<h4>
5.2.6. Loops </h4>
<font color="#0000ff">
<pre>
while (stuff) {
/*...*/
}
do {
/*...*/
} while(stuff)
for (this; that; those) {
/* Always use curlies, even if no body. */
}
/*
** If no body, do this...
*/
while (stuff)
{}
for (this; that; those)
{}
</pre>
<font color="#000000">
<h3>
5.3. Preprocessing </h3>
<h4>
5.3.1. Nesting</h4>
Nested #ifdefs, #ifndefs and #ifs should be indented by two spaces for
each level of nesting. For example:
<font color="#0000ff">
<pre>
#ifdef GUAVA
#ifndef PAPAYA
#else /* PAPAYA */
#endif /* PAPAYA */
#else /* not GUAVA */
#endif /* not GUAVA */
</pre>
<font color="#000000">
<h2>
6. Portability</h2>
<h3>
6.1. Architecture specifics</h3>
Avoid relying on properties of a specific machine architecture unless
necessary, and if necessary localise such dependencies. One solution is
to have architecture-specific macros to hide access to
machine-dependent code.
Some machine-specific properties are:
<ul>
<li> Size (in bits) of C builtin datatypes (short, int, long, float,
double).
<li> Byte-order. Big- or little-endian (or other).
<li> Alignment requirements.
</ul>
<h3>
6.2. Operating system specifics</h3>
Operating system APIs differ from platform to platform. Although
most support standard POSIX calls such as `read', `write'
and `unlink', you cannot rely on the presence of, for instance,
System V shared memory, or BSD sockets.
<p>
Adhere to POSIX-supported operating system calls whenever possible
since they are widely supported, even by Windows and VMS.
<p>
When POSIX doesn't provide the required functionality, ensure that
the operating system specific calls are localised.
<h3>
6.3. Compiler and C library specifics</h3>
ANSI C compilers are now widespread and hence we needn't pander to
old K&R compilers. However compilers (in particular the GNU C compiler)
often provide non-ANSI extensions. Ensure that any use of compiler
extensions is localised and protected by #ifdefs.
<p>
Don't rely on features whose behaviour is undefined according to
the ANSI C standard. For that matter, don't rely on C arcana
even if they <em>are</em> defined. For instance,
<tt>setjmp/longjmp</tt> and ANSI signals often have subtle differences
in behaviour between platforms.
<p>
If you write threaded code, make sure any non-reentrant code is
appropriately protected via mutual exclusion. The biggest cause
of non-reentrant (non-threadsafe) code is function-static data.
Note that some C library functions may be non-reentrant. This may
or may not be documented in the man pages.
<h3>
6.4. Environment specifics</h3>
This is one of the most important sections in the coding standard.
Here we mention what other tools Mercury depends on.
Mercury <em>must</em> depend on some tools, however every tool that
is needed to use Mercury reduces the potential user base.
<p>
Bear this in mind when tempted to add YetAnotherTool<sup>TM</sup>.
<h4>
6.4.1. Tools required for Mercury</h4>
In order to run Mercury (given that you have the binary installation), you need:
<ul>
<li> A shell compatible with Bourne shell (sh)
<li> GNU make
<li> One of:
<ul>
<li> The GNU C compiler
<li> Any ANSI C compiler
</ul>
</ul>
In order to build the Mercury compiler, you need the above and also:
<ul>
<li> gzip
<li> tar
<li> Various POSIX utilities: <br>
awk basename cat cp dirname echo egrep expr false fgrep grep head
ln mkdir mv rmdir rm sed sort tail
<li> Some Unix utilities: <br>
test true uniq xargs
</ul>
<p>
In order to modify and maintain the source code of the Mercury compiler,
you need the above and also:
<ul>
<li> Perl <font color="#ff0000">XXX: Which version?<font color="#000000">
<li> CVS
<li> autoconf
<li> texinfo
<li> TeX
</ul>
<p>
For Prolog support, you need also need one of:
<ul>
<li> A NU-Prolog installation
<li> A SICStus Prolog installation
</ul>
<h4>
6.4.2. Documenting the tools</h4>
If further tools are required, you should add them to the above list.
And similarly, if you eliminate dependence on a tool, remove
it from the above list.
<h2>
7. Coding specifics</h2>
<ul>
<li> Do not assume arbitrary limits in data structures. Don't
just allocate `lots' and hope that's enough. Either it's
too much or it will eventually hit the wall and have to be
debugged.
Using highwater-marking is one possible solution for strings,
for instance.
<li> Always check return values when they exist, even malloc
and realloc.
<li> Always give prototypes (function declarations) for functions.
When the prototype is in a header, import the header; do not
write the prototype for an extern function.
<li> Stick to ANSI C whenever possible. Stick to POSIX when
ANSI doesn't provide what you need.
Avoid platform specific code unless necessary.
<li> Use signals with extreme austerity. They are messy and subject
to platform idiosyncracies even within POSIX.
<li> Don't assume the sizes of C data types. Don't assume the
byteorder of the platform.
<li> Prefer enums to lists of #defines. Note that enums constants
are of type int, hence if you want an enumeration of
chars or shorts, then you must use lists of #defines.
<li> Parameters to macros should be in parentheses.
<font color="#0000ff">
<pre>
#define STREQ(s1,s2) (strcmp((s1),(s2)) == 0)
</pre>
<font color="#000000">
</ul>
<hr>
<!-------------------------->
Comments? Mail <a href = "mailto:mercury at cs.mu.oz.au">mercury at cs.mu.oz.au</a>,
or see our <a href = "../email.html" >contact</a> page.<br>
Last update was $Date: 1998/05/15 06:40:00 $ by $Author: zs $@cs.mu.oz.au. <br>
Note: This coding standard is an amalgam of suggestions from the
entire Mercury team, not ncessarily the opinion of any single author.
</body>
</html>
New File: information/developers/remote_cvs.html
===================================================================
<html>
<head>
<title>The Mercury Project: Remote CVS Access </title>
</head>
<body bgcolor="#ABCDEF" text="#000000">
<h2>Using the CVS client to remotely access the Mercury CVS archive</h2>
Author: Tyson Dowd -- trd at cs.mu.oz.au
<p>
Almost all work in the Mercury project is under revision control using
CVS. The sources, documentation, test-cases, webpages and samples
are all stored under various modules of the CVS repository on
filesystems here at the University of Melbourne. CVS allows
client-server access to this repository. This document describes how
to use the CVS archive remotely.
<p>
You need:
<ul>
<li> A version of CVS with client server support (1.9 works fine)
installed at the remote end. Probably anything newer than
1.5 will work OK.
<li> A TCP/IP connection to the Internet.
</ul>
Preliminaries:
<ul>
<li> The CVS server uses password authentication. You need to
have a password installed in CVS's password file on
the server end.
<li> Generate a password using standard UNIX /etc/passwd style
passwords. *Do not* use your normal password. A good way to
do this is change your password to something, copy the line
from /etc/password, then change it back. Only the username and
encrypted password are needed.<p>
e.g. trd:s9FOR1a8DOxDs<p>
(If your system uses shadow password files, the password field
of /etc/passwd will not be meaningful; mail us if there is a problem).
<p>
If your encrypted passwd after you change it back looks different
from what it looked like originally, do not worry. The encrypted
form of your password depends not only on your password but also
on a 16-bit value known as the "salt" that is generated randomly
every time you change your password, and which is recorded in
the encrypted password field itself.
<li> Send the line with the username and encrypted password to the
Mercury team, who will install it for you. If you have access to
the CVS repository at the University of Melbourne, you can just
add it to the file /home/mercury1/repository/CVSROOT/passwd.
You also need an account on the machines where the cvs server
is running which is in group mercury (the account doesn't need
to be able to rlogin). If you can't create one yourself,
you'll need to ask someone in the Mercury team to create one
for you. (Mercury team - add a line to the CVS passwd file,
and an account with * in the password field, /dev/null as
its shell, and in group mercury, on hydra and mercury).
<li> Also, tell us what domain you're going to be accessing the
repository from, so we can adjust our security setup to allow
you access. If you don't say, we'll assume it is the same as your
email address. (Mercury team - modify /etc/hosts.allow to
allow that domain).
<li> Access via Windows or other non-UNIX platforms is untested,
but theoretically possible.
</ul>
Then (once you've been added to the passwd file):
<ul>
<li> Set your CVSROOT environment variable to <p>
<ul>
<li>:pserver:username at mercury.cs.mu.oz.au:/home/mercury1/repository
</ul>
or
<ul>
<li>:pserver:username at hydra.cs.mu.oz.au:/home/mercury1/repository
</ul>
(we have two because sometimes one of the machines is down -
it doesn't matter much which one you use).
<p>
Make sure this environment variable is exported (in sh
based shells, "export CVSROOT", in csh based shells, use
"setenv" to set the environment variable in the first place).
<li> Run "cvs login" to login to the server for the first time.
<li> CVS will remember your password from now on (it is rather
insecurely stored in a slightly jumbled manner in ~/.cvspass),
so you rarely have to login again.
<li> You can do "cvs co mercury" to check out the main mercury
module. This can take a while over a slow connection, but you
should see pretty steady progress messages, eg:
<pre>
U mercury/.INSTALL.in
U mercury/.README.in
U mercury/.cvsignore
U mercury/BUGS
U mercury/COPYING
U mercury/COPYING.LIB
etc
</pre>
<li> The CVS modules you might need access to are:
<dl>
<dt>mercury <dd> the mercury compiler, runtime, library,
extras and documentation. (8.9Mb)
<dt>tests <dd> test cases for the compiler (0.72Mb)
<dt>clpr <dd> the CLP(R) interface (0.88Mb)
<dt>www <dd> the www page (7.5Mb - lots of papers)
</dl>
CVS should compress most of this stuff while sending it.
</ul>
NOTE:
<ul>
<li> Developers should subscribe to the mercury-developers mailing
list, to keep up-to-date on development discussion, and
to be able to participate in discussions about code they
want to change. This is a forum to ask questions about how
to change something, discuss design trade-offs, and report
on any development that you suspect will influence others.
(Traffic is moderately high in this mailing list - between
100 and 300 messages per month, so you should filter it if
possible).
<li> Before committing any code, read the policy on reviews for the
Mercury system. This can be found in the mercury CVS
module:
<ul>
<li> mercury/compiler/notes/reviews.html
</ul>
or on the web page:
<ul>
<li>http://www.cs.mu.oz.au/research/mercury/developer/reviews.html
</ul>
Basically, we don't commit broken code into the repository,
and we don't commit un-reviewed code.
<li> We may decide to limit access to read-only at first, which
makes it much harder for a remote user to make a mistake.
In this case, you'll need to contact us if you need to commit
something to the repository.
<li> You'll need to be familiar with CVS to keep up to date with
the development tree. If you haven't used it before, read the
info pages on CVS and the documentation that comes with it.
If you have any questions, just ask.
</ul>
<p>
<hr>
<p>
Comments? Mail <a href = "mailto:mercury at cs.mu.oz.au">mercury at cs.mu.oz.au</a>,
or see our <a href = "../email.html" >contact</a> page.<br>
Last update was $Date: 1998/01/08 02:13:50 $ by $Author: trd $@cs.mu.oz.au
</body>
</html>
New File: mailing-lists/create_archive
===================================================================
#!/bin/sh
#
# Shell script to create all the Mailing List archives up to the current
# month.
# This command must be run in the current directory.
#
dir=/home/mercury/public/mailing_lists/
day=`date '+%d'`
month=`date '+%m'`
year=`date '+%y'`
if [ $day = "01" ]
then
month=`expr $month - 1`
month=`printf "%02d\n" $month`
fi
archive2html.sh -d $dir -f mercury-users -m 01 -y 97
m=02
y=97
while [ $y -le $year ]
do
while [ $m -le 12 ]
do
if [ $y -eq $year -a $m -gt $month ]
then
break
fi
for mail in mercury-users mercury-developers
do
echo ./archive2html.sh -d $dir -f $mail -m $m -y $y
./archive2html.sh -d $dir -f $mail -m $m -y $y
done
m=`expr $m + 1`
m=`printf "%02d" $m`
done
m=01
y=`expr $y + 1`
done
----
+----------------------------------------------------------------------+
| Peter Ross M Sci/Eng Melbourne Uni |
| petdr at cs.mu.oz.au WWW: www.cs.mu.oz.au/~petdr/ ph: +61 3 9344 9158 |
+----------------------------------------------------------------------+
More information about the developers
mailing list