$Id: compile.txt,v 1.1.1.2 2002/03/28 00:03:28 andrew_belov Exp $

INTRODUCTION

        This  is a collection of  developer's  notes for the open-source
        ARJ project.


CODE ORGANIZATION CONSIDERATIONS: 

        For clarity, handle NULL as it might be !=0, so actions like "if
        (!strchr(...))"  are depreciated.

        The    data structures  are    described with a simple  "struct"
        statement. "typedef struct" is  only used to emphasize a complex
        type with  a "hidden" implementation,  like FILE in  C, which is
        different in   various   C  implementations.  In   other  words,
        "typedef struct" construct has never to be  used in ARJ modules,
        although it takes longer time to  type the extra word, "struct",
        in declarations.

        Some variables may  have  doubtful names, like  bytes_written in
        hollow_decode(). These     result  from  countless     cut+paste
        operations.

        Despite our  attempts to keep  the code scattered within several
        files,  DOS-hosted   compilers may   run  out of   memory  while
        compiling the source. Even more,   the fact that some files  are
        larger than 64K adversely affects the portability.

        Be careful when you   convert   an array definition   like  char
        p[SOME_CONSTANT]; to a pointer for dynamic allocation.  The size
        of such array may be referenced with sizeof() statement.

        No dependencies are  made on the  *.H files (and actually  there
        are  very  deep,   sometimes even circular  dependencies).  Most
        oftenly, all targets  must be  recompiled  when  an .H file   is
        changed.   An exception may be  the introduction of an equate or
        declaration - in this case, obviously, there is no need to force
        the recompile.


CODING STYLE

        ** TODO: this section will have to be revised **

        The coding style is distinct  in that the single space character
        is used as indentation.

        Oftenly, the conditional expressions are writen in the following
        form:

        (control_expression)?result1:result2. 

        Although  the brackets around  control_expression are a waste of
        space, we use them to highlight the control_expression.


COMPILER ISSUES

        Some compilers (e.g. Turbo C++  v 1.0) do not automatically pick
        default  include   file subdirectory  from  INCLUDE  environment
        varibable. In such cases,  the include path is usually specified
        in a corresponding .STS file.

        Dynamic linkage  with LIBC when using  IBM  C Set/2  is possible
        only if the libraries  have been converted to LINK386-compatible
        format (LIBCS.LIB) and the headers have  been patched to fix the
        stdin/stdout macro  abuse (results  in   null pointers once  the
        optimization is turned on)


COMPILER BUGS

        Microsoft C compiler v 6.00A performs optimizations incorrectly,
        resulting in broken code. Therefore, register optimizations have
        been disabled.

        Microsoft C compiler v 6.00A (unsure about the others) prefers a
        function over the label with the same name in ASM clauses within
        functions.

        Microsoft  Visual C v 1.00 compiler   (CL.EXE v 8.00) fails when
        /Os  is specified. /Olerg is  used  as a  workaround to this. An
        extensive analysis of  the exact optimization switch that causes
        the failure has not    been yet performed so   the  optimization
        efficiency has been scaled down to pretty inaccurate.

        This  hasn't been   investigated thoroughly but   it  seems that
        Borland C++ v 4.00 is not able to link COM files with C0T.OBJ. A
        workaround for  this is to use C0T.OBJ  from Borland  C++ v 3.10
        package instead.

        MASM  v 6.00  occasionally  may end up   with an exception under
        OS/2, leaving a blank object  file and therefore obstructing the
        compilation.  Microsoft claims that it has been fixed in version
        6.01.


PLATFORM ISSUES

        When compiling under DOS, version 4.00 or higher is required due
        to use  of "@" modifiers  in MAKEFILE.  Compiled executables may
        be  run  in  lower  versions of DOS   if it's   allowed by their
        implementation.
