@node Development, , , Top

@section Coding Standards

@subsection Source indentation
@cindex source indentation
@cindex indentation standards

Most of the DJGPP sources are formatted in a standard way; please
observe and preserve this formatting when writing new code.

The indentation style generally looks like this:

@example
 if (foo)
 @{
   bar(baz);
 @}
@end example

@noindent
That is, the braces are on a separate line and in the same column as the
@code{if} (or @code{for}, or @code{while}) clause that opens the block.

@pindex emacs@r{, and DJGPP-style indentation}
Here's how to set up Emacs's C Mode for this indentation style:

@lisp
(c-add-style
 "DJ"
 '((c-basic-offset . 2)
   (c-comment-only-line-offset . (0 . 0))
   (c-offsets-alist . ((substatement-open . 0)
		       (label . 0)
		       (statement-case-open . +)
		       (statement-cont . +)
		       (arglist-intro . c-lineup-arglist-intro-after-paren)
		       (arglist-close . c-lineup-arglist)
		       ))
   ))

(c-set-style "DJ")
@end lisp

@noindent
@pindex indent@r{, reindenting to DJGPP style}
And here's the list of options for the GNU @code{indent} program, to be
put on your @file{.indent.pro} profile file, in case you need to
reformat your sources to comply with the DJGPP style:

@example
/* DJ */
-nbad -bap -nbc -bbo -bl -bli0 -brs -ncdb -nce -cp1 -cs -di2
-nfc1 -fca -hnl -i2 -ip2 -ci0 -lp -npcs -nprs -psl -nsc -nsob
@end example

@cindex stubs
@subsection Stubs

A C application's namespace should not be polluted with non-ANSI
and non-POSIX functions from the C libraries, unless the application
explicitly uses these symbols.  An example of a non-ANSI and non-POSIX
function is @code{uclock} (@pxref{uclock, , uclock, libc}).

But what happens if you wish to call a non-ANSI and/or
non-POSIX function from C library code?  The actual implementation
is placed in the C library's private namespace with a stub function
that calls the implementation.  Consider @code{uclock} ---
the library would use the @code{__uclock} function internally,
but application code would use the stub @code{uclock}.

@cindex @file{libc/stubs.h}
Functions that are stubbed have an entry in the include file
@file{libc/stubs.h}, e.g.:

@example
#define uclock __uclock
@end example

Any C library sources defining or calling the implementation
should include @file{libc/stubs.h} as the first include file.
This is so that we can refer to, e.g., @code{uclock} as @code{uclock}
in the library code, but the library code will actually define/call,
e.g., @code{__uclock} and will not pollute the application namespace.

The stub files are assembly language files generated automagically
from @file{libc/stubs.h} as part of the C library build process.

NB: The private name, e.g., @code{__uclock}, is @strong{not} part of
the published API.

@subsection Far pointers usage
@cindex @code{_far*} functions in the library

If a library function uses one of the @code{_far*} far pointer
functions, it should include @file{libc/farptrgs.h} instead of
@file{sys/farptr.h}.  The inline functions in @file{farptrgs.h} use the
@sc{gs} register instead of @sc{fs}, to avoid clobbering @sc{fs} which
might be used by the application.

@subsection Filename manipulation

When manipulating filenames, don't use the ctype functions from
@file{ctype.h}, because they are locale sensitive.  For example,
instead of using @code{tolower} (@pxref{tolower, , tolower, libc}),
convert the case with explicit code.

@subsection Assertions
@cindex Assertions

Assertions should not generally be used in library code.  To catch an error,
the code should check for the error and return an error code.  Using
@code{assert} (@pxref{assert, , assert, libc}) causes the debug
and final release (@samp{NDEBUG} defined) versions of the code to differ,
so that the final release is not as well tested.

@subsection Coping with restarted programs
@cindex coping with restarted programs
@cindex @code{__bss_count} and restarted programs

Uninitialised static and global data is placed in the @code{.bss} section.
@dfn{BSS} stands for Block Started by Symbol.  The @code{.bss} section
is zeroed by the start-up code.

Initialised static and global data is placed in the @code{.data} section.

So it would seem that one can rely on static and global variables being
initialised to zero or some specified value.  Unfortunately this may not
be true, where programs are unexecuted and then restarted ---
Emacs is the primary example.

Part of Emacs's build procedure is that Emacs unexecutes (dumps) itself to
a file.  The dumping process records the value of each variable at
the time of the dump to a file.  The symbols in the @code{.bss} section
are moved to the @code{.data} section.  The values at the time of the dump
are recorded, not the original values.  So if the library code is
relying on the value of a static or global variable, e.g., to see whether
it needs to initialise some device or allocate memory, then it may break
when the program restarts.

Fortunately there is a way that library code can detect a restart.
The variable @code{__bss_count} contains a counter of the number of times
that the program has been started --- it is incremented by the start-up
code.  A routine can store @code{__bss_count} and then check whether it needs
to initialise its data by comparing @code{__bss_count} with its stored value.
Here is an example:

@example
#include <string.h>
#include <libc/bss.h>

extern int do_something_interesting (const int n);

static int my_bss_count = -1;
static int my_array[20];

int
myfunc (const int n)
@{
  if (my_bss_count != __bss_count)
    @{
      my_bss_count = __bss_count;
      memset(my_array, 0, sizeof(my_array));
    @}

  if (n >= 20)
    return 0;

  if (!my_array[n])
    my_array[n] = do_something_interesting(n);

  return(my_array[n]);
@}
@end example

For more details see @file{src/libc/crt0/crt1.c} in the DJGPP libc sources.

@section The DJGPP Build System

@subsection Profiling

@file{src/gcc.opt} controls how the DJGPP sources are compiled.
To build the C libraries for profiling, add the profiling options
(e.g., @samp{-pg}) to @file{gcc.opt}, one option per line.  The library
will need to be rebuilt from scratch for the new options to take effect,
so a @samp{make clean} is needed before rebuilding in
the directory of interest, e.g.:

@example
cd /path/to/djgpp/sources
cd src
echo "Adding profiling option to gcc.opt"
echo -pg >> gcc.opt
cd libc
echo "Building a profiling version of libc"
make clean
make
@end example

For example of how some of the sources are built without profiling,
please see @file{src/libc/crt0/makefile} to see how the profiling
support code, @file{src/libc/crt0/mcount.c}, is built.

There are currently some problems with profiling support.
The math co-processor support code, @file{emu387.dxe},
in @file{src/libemu} cannot be built with profiling.

@section Texinfo documentation

@subsection Formatting

@itemize
@item
Use two spaces after every period/full-stop ending a sentence.

@item
Don't use capital letters for emphasis---use @samp{@@strong@{@}} instead.

@item
Put a comma or colon after ``e.g.''.

@item
When ``i.e.'' or ``etc.'' is followed by a space, use @samp{@@:} after it,
to indicate that that the final period does not end
the sentence. E.g.: @samp{i.e.@@:}.

@item
Don't put a newline between a function's return type and its name, e.g.:

@example
int
somefunc (void);
@end example

is incorrect;

@example
int somefunc (void);
@end example

is correct.

@item
When introducing a new term, it is usually a good idea to use
@samp{@@dfn@{@}} to mark it as a definition.  It may also be a good idea
to add it to the concept index using @samp{@@cindex@{@}}.  E.g.:

@example
@@cindex definition

This is a @@dfn@{definition@}.
@end example

@item
Command-line options should use the @samp{@@samp@{@}} or
@samp{@@option@{@}} mark-up.  @samp{@@option@{@}} is new in Texinfo 4.0.

@item
Names of programs should use @samp{@@command@{@}} (unless program's name
has become a proper name, like GCC or GDB).

@item
Constants like @code{EINVAL} should be enclosed in @samp{@@code@{@}}.

@item
Environment variables like @env{LOGNAME} should be enclosed in
@samp{@@env@{@}}.

@item
Avoid the urge to use @samp{@@ref@{@}} or variant in the middle of sentence,
because it will look ugly in info documentation and terrible in printed
documentation.  Instead use a textual reference followed by a comma followed
by the reference command, e.g.:

@example
@@code@{yabbadabbadoo()@}, @@ref@{yabbadabbadoo()@}.

@end example

@item
Be aware of how you use the @samp{-} character.  Use the following mark-up
correctly:

@itemize @bullet
@item
@samp{@@minus@{@}} to insert a minus sign;

@item
@samp{---} to insert an em-dash---do not put spaces on either side of
@samp{---};

@item
@samp{-} to hyphenate;

@item
@samp{@@-} to insert a discretionary hyphenation point.
@end itemize

@item
Use @code{@@uref} to refer to a URL.  texinfo also has @code{@@url}
for inserting URLs, but @code{@@uref} is more useful when texinfo
is formatted into HTML.  The Texinfo manual discourages
the use of @code{@@url}.

@item
Under the subheading @samp{Portability}, @samp{@@portability} should be
used to indicate whether a feature is specified in the ANSI C and POSIX
standards.  For example:

@example
@@subheading Portability

@@portability !ansi, posix
@end example

Please note that @samp{@@portability} is not used to indicate whether
the DJGPP implementation complies with the standards listed.  Instead,
@samp{@@port-note} may be used to describe implementation-specific details:

@example
@@port-note ansi The buffer size limit is imposed by DJGPP.
@end example

@samp{@@portability} and @samp{@@port-note} are DJGPP-specific extensions
of texinfo (@pxref{Top, , texinfo, texinfo}) that are expanded into normal
texinfo by @code{mkdoc}.  @code{mkdoc} is part of the DJGPP sources.  It is
used to build the C library documentation (@pxref{Top, , libc, libc}).
Therefore, @samp{@@portability} and @samp{@@port-note} should only be used
in DJGPP's C library documentation.

@item
When writing prototypes in header files remember to prefix any formal
arguments that you use with the underscore character (@samp{_}) to avoid
polluting the name space.

@item
Finally, for some relevant texinfo technique, look at the source
of this page in the DJGPP sources---@file{src/docs/kb/contrib.txi}.
@end itemize
