Initial import of upstream branch

Initial import of upstream branch


git-archimport-id: srivasta@debian.org--2003-primary/dist--upstream--3.70--base-0

1 files changed, 189 insertions, 0 deletions

diff --git a/jmake/NOTES b/jmake/NOTES
new file mode 100644
index 0000000..a11618d
--- /dev/null
+++ b/jmake/NOTES
@@ -0,0 +1,189 @@
+The syntax in Jmake.rules is not elegant at all, but:
+
+	- It is easy to parse (like sendmail.cf or troff files).
+	- The rules are not supposed to change very often.
+	- It is simple enough to be mastered in five minutes. :-)
+
+Here is a small description:
+
+o To deal with various cpp implementations:
+
+Final @!\ means: end of line, next line starts at the left margin.
+Final @@\ means: end of line, next line is to be indented by one tab.
+
+The conversion occurs during Pass1.
+
+
+o Symbol definitions
+
+>SYMBOL: defines the symbol (Pass 1).
+?SYMBOL:<text>: keeps <text> iff SYMBOL is defined (Pass 2).
+%SYMBOL:<text>: keeps <text> iff SYMBOL is not defined (Pass 2).
+
+The ?SYM can be nested (logical AND), as in:
+
+	?SYMBOL:%TOKEN:text		/* Keeps text if SYMBOL and not TOKEN */
+
+To implement a logical OR, see below.
+
+
+o Commands
+
+Commands can be passed to 'jmake'. They start with a leading '|'.
+
+Available commands are:
+
+|suffix <sx>: adds <sx> to the .SUFFIXES: list in the makefile (Pass 1 & 2).
+|rule:<text>: adds <text> to the building rule section (Pass 1 & 2).
+|rule: <text>: same as before, with a leading tab.
+|skip: skips text until a line starting with '-skip' is found (Pass 2).
+|expand <pattern>: expand lines until '-expand' with <pattern> (Pass 2).
+|once <symbol>: text up to '-once' appears only the first time (Pass 1).
+
+Thus, a way to implement a logical OR could be:
+
+	/* Implements SYMBOL or not TOKEN */
+	?SYMBOL:text			/* Keeps text if SYMBOL */
+	%SYMBOL:|skip
+		%TOKEN:text			/* Keeps text if not TOKEN */
+	-skip
+
+Actually, this is ugly, because the text has to appear twice.
+Fortunately, I did not use it. :-)
+
+The '|' commands cannot be nested. In particular, due to the simple
+implementation of '|skip', it is impossible to put '|skip' inside
+a skipped part. However, a '|once' section may have '|skip' sections.
+
+But actually, as you have surely already guessed, the best way to
+implement a logical OR is to use De Morgan's Law:
+
+	not (p or q) <=> not p and not q
+
+	/* Implements SYMBOL or not TOKEN (attempt #2) */
+	%SYMBOL:?TOKEN:|skip
+	text					/* If SYMBOL or not TOKEN */
+	-skip
+
+Who said they don't care ? ;-)
+
+o Expansion
+
+Expansion is done with the 'expand' command.  It has been provided to
+avoid some cumbersome writings in makefiles when you have to repeat some
+silly lines that only differ in file names, for instance.  Let's look at
+an example first:
+
+	|expand a!foo bar! b!yes no!
+	!a::
+		echo !a, !b
+	-expand
+
+Then two rules will be printed, and the values of (a,b) for the first
+will be (foo, yes), for the second (bar, no).  Substitution is controled
+by the '!' character.  If the word to be substituted is part of another
+one, detach with the ^^ construct as in:  !b^^c.  It is possible to
+use Makefile macros in the <pattern>, and they will be expanded by
+jmake.  If this is not what you want, escape the first '$' sign (this is
+a Makefile escape, i.e. you must double the '$', not precede it with a
+backslash). A // stands for the null substitution value.
+
+Here is another example which shows how the macro Expand can be used.
+It is defined in Jmake.rules as:
+
+	#define Expand(rule, pattern) @!\
+	|expand pattern @!\
+	rule @!\
+	-expand
+
+So we can write in the Jmakefile:
+
+	|skip
+	A = foo bar
+	-skip
+
+	#define Rule @!\
+	$(DIR)/!a^^.o: !a^^.o @@\
+		$(CC) -c !a^^.c @@\
+		$(MV) !a^^.o $(DIR)
+	
+	Expand(Rule, a!$(A)!)
+
+which will generate in Makefile.SH:
+
+	$(DIR)/foo.o: foo.o
+		$(CC) -c foo.c
+		$(MV) foo.o $(DIR)
+
+	$(DIR)/bar.o: bar.o
+		$(CC) -c bar.c
+		$(MV) bar.o $$(DIR)
+
+The 'A' declaration has been surrounded by skip, so that it does
+not appear in the generated Makefile.SH, but it will be taken into
+account by jmake for the substitution in the pattern.
+
+The number of expansions is determined by the number of possible
+values for the _first_ parameter. If other parameters have less
+substitution values, they will get void ones.
+
+It is possible to add a regular expression at the end of '-expand'.
+This regular expression will be removed from the final set of expansion
+at the end of each line.  It is also possible to do substitutions in the
+expanded item, by using the syntax (if 'f' is the expanded variable)
+!f:<p>=<q> where <p> and <q> are two regular expressions (without
+spaces).  The pattern <p> will be replaced by pattern <q> (only the
+first occurrence will be replaced).
+
+Finally, you may refer in the expanded section to variables whose value
+is computed via another expansion, which makes it easy to define generic
+Jmakefiles.
+
+Example:
+
+	SRC = foo.c bar.c
+	OBJ = \
+	|expand f!$(SRC)!
+		!f:\.c=\.o \
+	-expand \\
+	INC = \
+	|expand f!$(OBJ)!
+		!f:\.o=\.h \
+	-expand \\
+
+which will generate in Makefile.SH:
+
+	SRC = foo.c bar.c
+	OBJ = \
+		foo.o \
+		bar.o
+	INC = \
+		foo.h \
+		bar.h
+
+Do not forget to protect special characters in your regular expressions such
+as backslash, point, etc...
+
+o Once
+
+The once command is tagged with a name. The first time the name appears,
+the once construct is ignored and the text up to '-once' will be copied
+in the generated Makefile.SH.  However, future occurences of the same
+name will be ignored (once will behave like skip).
+
+Example:
+
+	|once this_is_a_name
+	<text>
+	-once
+
+o Initializations
+
++<line>: Puts the whole line in the initialization section (Pass 1 & 2).
+++SYMBOL <value>: Adds <value> to the SYMBOL macro (Pass 1 and 2).
+
+o User-defined variables
+
+CFLAGS: added flags to C compiler
+DPFLAGS: cpp flags to be added to mkdep for dependency
+LDFLAGS: flags/libraries to be added at linking stage