$Id: compile.txt,v 1.2 2002/12/13 22:29:37 andrew_belov Exp $ 

INTRODUCTION 

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


HOW TO COMPILE 

        UNIX-like systems,  as well as OS/2  EMX,  need to be configured
        first.   Run "cd gnu;  autoconf; ./configure; cd .."  to proceed
        with the standard GNU configuration process.

        Tip: the   "configure" script would  be  different for UNIX-like
        systems and OS/2  EMX. That is the  reason for not including  it
        into the source code distribution.

        Next, the "prepare" stage of makefile must be ran for the chosen
        compiler.   That is, "nmake prepare"  or  "gmake -f makefile.gnu
        prepare" is  required before the  actual compile may take place.
        At this stage, a subdirectory tree is established to accommodate
        a particular build  configuration (see the makefile for  details
        on available options). Example:

        gmake -f makefile.gnu DEBUG=1 prepare
        gmake -f makefile.gnu 

        ARJ  may be  packaged  in a SFX  file  by choosing the "package"
        target instead of    the default target, "all".    The  packages
        created by  the open-source distribution   would  be similar  to
        those distributed by ARJ  Software Russia.  Unlike the  previous
        closed-source releases, the  open-source ARJ distribution  is no
        longer stamped with a signature known as ARJ-SECURITY.


CODE ORGANIZATION CONSIDERATIONS 

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

        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, the
        "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. 

        "ASR fix:", followed by a brief  description and a date, denotes
        a  response to a feature request  or bug report. In these areas,
        the behavior of ARJ might  be intentionally changed and may  not
        be compatible with the original product by ARJ Software, Inc. 


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) 

        The  "-O2" GCC optimization   parameter may  impose problems  in
        newer releases of  GCC.   Special attention should  be  paid  to
        GCC/EMX in OS/2  which is presently  frozen  at 3.0.3/3.0.4.  An
        example of tight optimization for AMD K7 series that is known to
        work  with GCC v 3.0.3  follows  [insert  this under "os2*)"  in
        gnu/configure.in prior to compiling, merge  to make up a  single
        line]:

	CFLAGS="-O2 -fno-expensive-optimizations -funroll-loops
        -fpeephole2 -march=athlon -D_OS2"


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.
