$Id: compile.txt,v 1.6 2003/05/07 18:55:51 andrew_belov Exp $ INTRODUCTION         This is  a collection of  developers' 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;  autoheader; 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,  run  GNU  make in the toplevel directory.  If you specify        "DEBUG=1", the executables will be built with debug information.        See GNUmakefile for details on available options).  Example:        gmake DEBUG=1        gmake        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.         One  may  use  the  "BUGBUG:",  "TODO:"  and  "FIXME:"  comments        ("BUGBUG:" is the  preferred style) to designate  code  portions        that need further work.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 GCC        v 2.9x through 3.1x.   Upgrade to GCC v  3.2 is suggested.  "-O2        -fno-expensive-optimizations" may also serve as a workaround.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.         The run-time library   in MS C    v 7.00 (even  with  the Sep'92        patches applied) has  some quirks with converting  dates to/from        unixtime. ARJ will report the  date in M_ARCHIVE_CREATED one day        before  than the  actual date. This  bug  does not occur neither        with MS C v 6.0, nor with subsequent releases (Visual C/C++).         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. Note that  this problem may no longer  be observed in ARJ,        as the ASM  portions have been  mostly eliminated in ARJ  v 2.71        and at early stages of ARJ v 2.72 development. 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.