fixed bug #604575

[fw/sdcc] / doc / sdccman.lyx

diff --git a/doc/sdccman.lyx b/doc/sdccman.lyx
index 509b48a6f8928b26f8dbede867708c16d2f611a2..8616060f4f8934218a4458806d5ebabc7917496b 100644 (file)
--- a/doc/sdccman.lyx
+++ b/doc/sdccman.lyx
@@ -1,5 +1,5 @@
-#LyX 1.2 created this file. For more info see http://www.lyx.org/
-\lyxformat 220
+#LyX 1.3 created this file. For more info see http://www.lyx.org/
+\lyxformat 221

 \textclass article
 \language english
 \inputencoding default
 \textclass article
 \language english
 \inputencoding default


@@ -26,7 +26,7 @@
 
 \layout Comment
 
 
 \layout Comment
 

-Please note: double dashed options (e.g.
+Please note: double dashed longoptions (e.g.

  --version) need three dashes in this document to be visable in html and
  pdf output.
 \layout Title
  --version) need three dashes in this document to be visable in html and
  pdf output.
 \layout Title


@@ -133,7 +133,7 @@ inline assembler code
 \newline 
 
 \newline 
 \newline 
 
 \newline 

-SDCC also provides an option (---cyclomatic) to report the relative complexity
+SDCC also provides an option (--cyclomatic) to report the relative complexity

  of a function.
  These functions can then be further optimized, or hand coded in assembly
  if needed.
  of a function.
  These functions can then be further optimized, or hand coded in assembly
  if needed.


@@ -148,7 +148,7 @@ SDCC also comes with a companion source level debugger SDCDB, the debugger
 
 \newline 
 The latest version can be downloaded from 
 
 \newline 
 The latest version can be downloaded from 

-\begin_inset LatexCommand \htmlurl{http://sdcc.sourceforge.net/}
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}

 
 \end_inset 
 
 
 \end_inset 
 


@@ -226,8 +226,8 @@ short is now equivalent to int (16 bits), it used to be equivalent to char
  (8 bits) which is not ANSI compliant
 \layout Itemize
 
  (8 bits) which is not ANSI compliant
 \layout Itemize
 

-the default directory where include, library and documention files are stored
- is now in /usr/local/share
+the default directory for gcc-builds where include, library and documention
+ files are stored is now in /usr/local/share

 \layout Itemize
 
 char type parameters to vararg functions are casted to int unless explicitly
 \layout Itemize
 
 char type parameters to vararg functions are casted to int unless explicitly


@@ -280,7 +280,7 @@ Other Resources
 \layout Standard
 
 The SDCC home page at 
 \layout Standard
 
 The SDCC home page at 

-\begin_inset LatexCommand \htmlurl{http://sdcc.sourceforge.net/}
+\begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}

 
 \end_inset 
 
 
 \end_inset 
 


@@ -330,153 +330,1396 @@ If you can think of some more, please send them to the list.
 Installation
 \layout Subsection
 
 Installation
 \layout Subsection
 

-Install and search paths
+Configure variables
+\layout Standard
+
+The install paths and default search paths are defined when running 'configure'.
+ The defaults can be overriden by
+\layout Standard
+
+...
+ TBD
+\newline 
+
+\newline 
+These configure variables are compiled into the binaries, and can only be
+ changed by rerunning 'configure' and recompiling SDCC.
+ The configure variables are written in 
+\emph on 
+italics
+\emph default 
+ to distinguish them from run time environment variables (see section search
+ paths).
+\newline 
+
+\newline 
+Cygwin is handled like a *nix, Mingw32 however belongs to the Win32 builds.
+ The SDCC team uses Mingw32 to build the official Windows binaries, because
+ it's
+\layout Enumerate
+
+open source, 
+\layout Enumerate
+
+a gcc compiler and last but not least
+\layout Enumerate
+
+the binaries can be built by cross compiling on Sourceforge's compile farm.
+\layout Standard
+
+The other Win32 builds using Borland, VC or whatever don't use 'configure',
+ but they (hopefully) use the default Win32 paths.
+\newline 
+
+\newline 
+These defaults are:
+\newline 
+
+\newline 
+
+\begin_inset  Tabular
+<lyxtabular version="3" rows="8" columns="3">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Variable
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+*nix default
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Win32 default
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+PREFIX
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+/usr/local
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\backslash 
+sdcc
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+EXEC_PREFIX
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+$PREFIX
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+$PREFIX
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+BINDIR
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+$EXECPREFIX
+\emph default 
+/bin
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+$EXECPREFIX
+\emph default 
+
+\backslash 
+bin
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+DATADIR
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+$PREFIX
+\emph default 
+/share
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+$PREFIX
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+DOCDIR
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+$DATADIR
+\emph default 
+/sdcc/doc
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+$DATADIR
+\emph default 
+
+\backslash 
+doc
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+INCLUDE_DIR_SUFFIX
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sdcc/include
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+include
+\end_inset 
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+LIB_DIR_SUFFIX
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sdcc/lib
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+lib
+\end_inset 
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset 
+
+
+\newline 
+
+\newline 
+
+\newline 
+'configure' also computes relative paths.
+ This is needed for full relocatability of a binary package and to complete
+ search paths (see section search paths below):
+\newline 
+ 
+\newline 
+
+\begin_inset  Tabular
+<lyxtabular version="3" rows="4" columns="3">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Variable (computed)
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+*nix default
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Win32 default
+\end_inset 
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+BIN2DATA_DIR
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+../share
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+..
+\backslash 
+
+\end_inset 
+</cell>
+</row>
+<row bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+PREFIX2BIN_DIR
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+bin
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+bin
+\end_inset 
+</cell>
+</row>
+<row bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+PREFIX2DATA_DIR
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+share/sdcc
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\end_inset 
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset 
+
+
+\layout Subsection
+
+Install paths
+\layout Standard
+
+1.
+ Binary files (preprocessor, assembler and linker)
+\layout Standard
+
+
+\begin_inset  Tabular
+<lyxtabular version="3" rows="2" columns="3">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Path
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+*nix default
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Win32 default
+\end_inset 
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+$EXEC_PREFIX
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+/usr/local/bin
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\backslash 
+sdcc
+\backslash 
+bin
+\end_inset 
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset 
+
+ 
+\newline 
+
+\newline 
+2.
+ Include files
+\layout Standard
+
+
+\begin_inset  Tabular
+<lyxtabular version="3" rows="2" columns="3">
+<features>
+<column alignment="block" valignment="top" leftline="true" width="1.6in">
+<column alignment="center" valignment="top" leftline="true" width="0in">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Path
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+*nix default
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Win32 default
+\end_inset 
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+$DATADIR/
+\newline 
+$INCLUDE_DIR_SUFFIX
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+/usr/local/share/sdcc/include
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\backslash 
+sdcc
+\backslash 
+include
+\end_inset 
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset 
+
+
+\newline 
+
+\newline 
+3.
+ Library files (the 
+\shape italic 
+model
+\shape default 
+ is auto-appended by the compiler, e.g.
+ small, large, z80, ds390 etc.)
+\layout Standard
+
+
+\begin_inset  Tabular
+<lyxtabular version="3" rows="2" columns="3">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Path
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+*nix default
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Win32 default
+\end_inset 
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+$DATADIR/$LIB_DIR_SUFFIX
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+/usr/local/share/sdcc/lib
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\backslash 
+sdcc
+\backslash 
+lib
+\end_inset 
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset 
+
+
+\newline 
+
+\newline 
+4.
+ Documentation
+\layout Standard
+
+
+\begin_inset  Tabular
+<lyxtabular version="3" rows="2" columns="3">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Path
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+*nix default
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Win32 default
+\end_inset 
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+$DOCDIR
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+/usr/local/share/sdcc/doc
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\backslash 
+sdcc
+\backslash 
+doc
+\end_inset 
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset 
+
+
+\layout Subsection
+
+Search paths
+\layout Standard
+
+Some search paths or parts of them are determined by configure variables
+ (in 
+\emph on 
+italics
+\emph default 
+, see section above).
+ Further search paths are determined by environment variables during runtime.
+ 
+\newline 
+The paths searched when running the compiler are as follows (the first catch
+ wins):
+\newline 
+
+\newline 
+1.
+ Binary files (preprocessor, assembler and linker)
+\newline 
+ 
+\begin_inset  Tabular
+<lyxtabular version="3" rows="4" columns="3">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" width="0in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Search path
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+*nix default
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Win32 default
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+$SDCC_HOME/
+\emph on 
+$PPREFIX2BIN_DIR
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+$SDCC_HOME/bin
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+$SDCC_HOME
+\backslash 
+bin
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Path of argv[0] (if available)
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Path of argv[0]
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Path of argv[0]
+\end_inset 
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+$PATH
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+$PATH
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+$PATH
+\end_inset 
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset 
+
+ 
+\newline 
+
+\newline 
+2.
+ Include files
+\newline 
+ 
+\begin_inset  Tabular
+<lyxtabular version="3" rows="6" columns="3">
+<features>
+<column alignment="block" valignment="top" leftline="true" width="1.5in">
+<column alignment="block" valignment="top" leftline="true" width="1.5in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Search path
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+*nix default
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Win32 default
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+---I dir
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+---I dir
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+---I dir
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+$SDCC_INCLUDE
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+$SDCC_INCLUDE
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+$SDCC_INCLUDE
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+$SDCC_HOME/
+\newline 
+
+\emph on 
+$PREFIX2DATA_DIR/
+\newline 
+$INCLUDE_DIR_SUFFIX
+\end_inset 
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+$SDCC_ HOME/
+\newline 
+share/sdcc/
+\newline 
+include
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+$SDCC_HOME
+\backslash 
+include
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+path(argv[0])/
+\newline 
+
+\emph on 
+$BIN2DATADIR/
+\emph default 
+
+\newline 
+
+\emph on 
+$INCLUDE_DIR_SUFFIX
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+path(argv[0])/
+\newline 
+../sdcc/include
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+path(argv[0])
+\backslash 
+..
+\backslash 
+include
+\end_inset 
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+$DATADIR/
+\emph default 
+
+\newline 
+
+\emph on 
+$INCLUDE_DIR_SUFFIX
+\end_inset 
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+/usr/local/share/sdcc/
+\newline 
+include
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+(not on Win32)
+\end_inset 
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset 
+
+ 
+\newline 
+
+\newline 
+ The option ---nostdinc disables the last two search paths.
+\newline 
+
+\newline 
+3.
+ Library files 
+\newline 
+With the exception of 
+\begin_inset Quotes sld
+\end_inset 
+
+---L dir
+\begin_inset Quotes srd
+\end_inset 
+
+ the 
+\shape italic 
+model
+\shape default 
+ is auto-appended by the compiler (e.g.
+ small, large, z80, ds390 etc.).
+ 
+\newline 
+
+\begin_inset  Tabular
+<lyxtabular version="3" rows="6" columns="3">
+<features>
+<column alignment="block" valignment="top" leftline="true" width="1.7in">
+<column alignment="block" valignment="top" leftline="true" width="1.2in">
+<column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
+<row topline="true" bottomline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Search path
+\end_inset 
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+*nix default
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Win32 default
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+

 \layout Standard
 
 \layout Standard
 

-Linux (and other gcc-builds like Solaris, Cygwin, Mingw and OSX) by default
- install in /usr/local.
- You can override this when configuring with ---prefix-path.
- Subdirs used will be bin, share/sdcc/include, share/sdcc/lib and share/sdcc/doc.
-\newline 
-Windows MSVC and Borland builds will install in one single tree (e.g.
- /sdcc) with subdirs bin, lib, include and doc.
-\newline 
+---L dir
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text

 
 

-\newline 
-The paths searched when running the compiler are as follows (the first catch
- wins):
-\layout Enumerate
+\layout Standard

 
 

-Binary files (preprocessor, assembler and linker):
-\newline 
-- the path of argv[0] (if available)
-\newline 
-- getenv(
-\begin_inset Quotes sld
+---L dir

 \end_inset 
 \end_inset 

+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text

 
 

-SDCC_BIN_PATH
-\begin_inset Quotes srd
+\layout Standard
+
+---L dir

 \end_inset 
 \end_inset 

+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text

 
 

-)
+\layout Standard
+
+$SDCC_LIB/

 \newline 
 \newline 

-- getenv(
-\begin_inset Quotes sld
-\end_inset 

 
 

-SDCCHOME
-\begin_inset Quotes srd
+\emph on 
+<model>

 \end_inset 
 \end_inset 

+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text

 
 

-)/bin
-\newline 
-- $PATH
-\layout Enumerate
+\layout Standard

 
 

-Include files:
-\newline 
-- -I dir
+$SDCC_LIB/

 \newline 
 \newline 

-- getenv(
-\begin_inset Quotes sld
-\end_inset 

 
 

-SDCC_INCLUDE_PATH
-\begin_inset Quotes srd
+\emph on 
+<model>

 \end_inset 
 \end_inset 

+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+$SDCC_LIB
+\backslash 

 
 

-)

 \newline 
 \newline 

-- getenv(
-\begin_inset Quotes sld
+
+\emph on 
+<model>

 \end_inset 
 \end_inset 

+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard

 
 

-SDCCHOME)/include
+$SDCC_HOME/

 \newline 
 \newline 

-- /usr/local/share/sdcc/include (gcc builds)
+
+\emph on 
+$PREFIX2DATA_DIR/

 \newline 
 \newline 

-- path(arv[0])/../include and then /sdcc/include (as a last resort for windoze
- msvc and borland builds)
-\layout Enumerate
+$LIB_DIR_SUFFIX/<model>
+\end_inset 
+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text

 
 

-Library files (the 
-\shape italic 
-model
-\shape default 
- is auto-appended by the compiler, e.g.
- small, large, z80, ds390 etc.):
+\layout Standard
+
+$SDCC_HOME/

 \newline 
 \newline 

-- -L dir
+share/sdcc/

 \newline 
 \newline 

-- getenv(
-\begin_inset Quotes sld
+lib/
+\emph on 
+<model>

 \end_inset 
 \end_inset 

+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text

 
 

-SDCC_LIB_PATH
-\begin_inset Quotes srd
+\layout Standard
+
+$SDCC_HOME
+\backslash 
+lib
+\backslash 
+
+\emph on 
+
+\newline 
+<model>

 \end_inset 
 \end_inset 

+</cell>
+</row>
+<row topline="true">
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text

 
 

-)/
-\shape italic 
-model
-\shape default 
+\layout Standard

 
 

+path(argv[0]/

 \newline 
 \newline 

-- getenv(
-\begin_inset Quotes sld
+
+\emph on 
+$BIN2DATADIR/
+\emph default 
+
+\newline 
+
+\emph on 
+$LIB_DIR_SUFFIX/<model>

 \end_inset 
 \end_inset 

+</cell>
+<cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text

 
 

-SDCCHOME
-\begin_inset Quotes srd
+\layout Standard
+
+path(argv[0])/
+\newline 
+../sdcc/lib/
+\emph on 
+<model>

 \end_inset 
 \end_inset 

+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text

 
 

-)/lib/
-\shape italic 
-model
-\shape default 
+\layout Standard
+
+path(argv[0]
+\backslash 

 
 \newline 
 
 \newline 

-- /usr/local/share/sdcc/lib/
-\shape italic 
-model
-\shape default 
- (gcc builds)
+..
+\backslash 
+lib
+\backslash 
+
+\emph on 
+<model>
+\end_inset 
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\emph on 
+$DATADIR/

 \newline 
 \newline 

-- path(argv[0])/../lib/
-\shape italic 
-model
-\shape default 
- and then /sdcc/lib/
-\shape italic 
-model
-\shape default 
- (as a last resort for windoze msvc and borland builds)
-\layout Enumerate
+$LIB_DIR_SUFFIX/<model>
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text

 
 

-Documentation (although never really searched for, you have to do that yourself
- :):
+\layout Standard
+
+/usr/local/share/sdcc/

 \newline 
 \newline 

-- getenv(
-\begin_inset Quotes sld
+lib/
+\emph on 
+<model>

 \end_inset 
 \end_inset 

+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text

 
 

-SDCCHOME
-\begin_inset Quotes srd
+\layout Standard
+
+(not on Win32)

 \end_inset 
 \end_inset 

+</cell>
+</row>
+</lyxtabular>

 
 

-)/doc
-\newline 
-- /usr/local/share/sdcc/doc (gcc builds)
-\newline 
-- /sdcc/doc (windoze msvc and borland builds)
+\end_inset 
+
+
+\layout Comment
+
+Don't delete any of the stray spaces in the table above without checking
+ the HTML output (last line)!

 \layout Standard
 
 \layout Standard
 

-So, for windoze it is highly recommended to set the environment variable
- SDCCHOME to prevent needless usage of -I and -L.
+\SpecialChar ~
+
+\newline 
+The option ---nostdlib disables the last two search paths.

 \layout Subsection
 
 \layout Subsection
 

-Linux and other gcc-based systems (cygwin, mingw, osx)
+Linux and other gcc-based systems (cygwin, mingw32, osx)

 \layout Enumerate
 
 
 \layout Enumerate
 
 


@@ -494,7 +1737,11 @@ Download the source package
 \series default 
 .src
 \series medium 
 \series default 
 .src
 \series medium 

-.tgz.
+.t
+\series default 
+ar.
+\series medium 
+gz.

 \layout Enumerate
 
 
 \layout Enumerate
 
 


@@ -507,7 +1754,7 @@ Bring up a command line terminal, such as xterm.
 Unpack the file using a command like: 
 \family sans 
 \series bold 
 Unpack the file using a command like: 
 \family sans 
 \series bold 

-"tar -xzf sdcc.src.tgz
+"tar -xzf sdcc.src.tar.gz

 \family default 
 \series default 
 "
 \family default 
 \series default 
 "


@@ -566,6 +1813,15 @@ Type
 \series default 
  This copies the binary executables, the include files, the libraries and
  the documentation to the install directories.
 \series default 
  This copies the binary executables, the include files, the libraries and
  the documentation to the install directories.

+\layout Standard
+
+On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
+)) fails to compile SDCC.
+ Fortunately there's also gcc 2.9.x installed, which works fine.
+ This compiler can be selected by running 'configure' with:
+\layout LyX-Code
+
+./configure CC=gcc2 CXX=g++2

 \layout Subsection
 
 Windows 
 \layout Subsection
 
 Windows 


@@ -577,7 +1833,8 @@ Windows Install Using a Binary Package
 Download the binary package and unpack it using your favorite unpacking
  tool (gunzip, WinZip, etc).
  This should unpack to a group of sub-directories.
 Download the binary package and unpack it using your favorite unpacking
  tool (gunzip, WinZip, etc).
  This should unpack to a group of sub-directories.

- An example directory structure after unpacking the mingw package is: c:
+ An example directory structure after unpacking the mingw32 package is:
+ c:

 \backslash 
 usr
 \backslash 
 \backslash 
 usr
 \backslash 


@@ -610,7 +1867,7 @@ Adjust your environment variable PATH to include the location of the bin
  directory or start sdcc using the full path.
 \layout Subsubsection
 
  directory or start sdcc using the full path.
 \layout Subsubsection
 

-Windows Install Using Cygwin and Mingw
+Windows Install Using Cygwin and Mingw32

 \layout Standard
 
 Follow the instruction in 
 \layout Standard
 
 Follow the instruction in 


@@ -793,124 +2050,83 @@ bin_vc to sdcc
 bin, and you can compile using sdcc.
 \layout Subsubsection
 
 bin, and you can compile using sdcc.
 \layout Subsubsection
 

-Windows Install Using Borland ......
-\layout Standard
-
-
-\shape italic 
-<pending>
-\layout Subsection
-
-Testing out the SDCC Compiler
-\layout Standard
-
-The first thing you should do after installing your SDCC compiler is to
- see if it runs.
- Type 
-\family sans 
-\series bold 
-"sdcc ---version"
-\family default 
-\series default 
- at the prompt, and the program should run and tell you the version.
- If it doesn't run, or gives a message about not finding sdcc program, then
- you need to check over your installation.
- Make sure that the sdcc bin directory is in your executable search path
- defined by the PATH environment setting (see the Trouble-shooting section
- for suggestions).
- Make sure that the sdcc program is in the bin folder, if not perhaps something
- did not install correctly.
-\newline 
-
-\newline 
+Windows Install Using Borland
+\layout Enumerate

 
 

-\series medium 
-SDCC binaries are commonly installed in a directory arrangement like this:
-\series default 
+From the sdcc directory, run the command "make -f Makefile.bcc".
+ This should regenerate all the .exe files in the bin directory except for
+ sdcdb.exe (which currently doesn't build under Borland C++).
+\layout Enumerate

 
 

+If you modify any source files and need to rebuild, be aware that the dependanci
+es may not be correctly calculated.
+ The safest option is to delete all .obj files and run the build again.
+ From a Cygwin BASH prompt, this can easily be done with the commmand:

 \newline 
 
 \newline 
 
 \newline 
 
 \newline 
 

-\begin_inset  Tabular
-<lyxtabular version="3" rows="3" columns="2">
-<features>
-<column alignment="left" valignment="top" leftline="true" width="0(null)">
-<column alignment="left" valignment="top" leftline="true" rightline="true" width="0(null)">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-/
-\series medium 
-usr/local/bin
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-
-\series medium 
-Holds executables(sdcc, s51, aslink, 
-\series default 
-...
-\series medium 
-)
-\end_inset 
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-/
-\series medium 
-usr/local/share/sdcc/lib 
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\family sans 
+\series bold 
+find .
+ 
+\backslash 
+( -name '*.obj' -o -name '*.lib' -o -name '*.rul' 
+\backslash 
+) -print -exec rm {} 
+\backslash 
+;
+\family default 
+\series default 

 
 

-\layout Standard
+\newline 

 
 

+\newline 
+or on Windows NT/2000/XP from the command prompt with the commmand:
+\newline 

 
 

-\series medium 
-Holds common C 
+\family sans 
+\series bold 
+
+\newline 
+del /s *.obj *.lib *.rul
+\family default 

 \series default 
 \series default 

-libraries
-\end_inset 
-</cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+ from the sdcc directory.
+\layout Subsection

 
 

+Testing out the SDCC Compiler

 \layout Standard
 
 \layout Standard
 

-/
-\series medium 
-usr/local/share/sdcc/include
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+The first thing you should do after installing your SDCC compiler is to
+ see if it runs.
+ Type 
+\family sans 
+\series bold 
+"sdcc ---version"
+\family default 
+\series default 
+ at the prompt, and the program should run and tell you the version.
+ If it doesn't run, or gives a message about not finding sdcc program, then
+ you need to check over your installation.
+ Make sure that the sdcc bin directory is in your executable search path
+ defined by the PATH environment setting (see the Trouble-shooting section
+ for suggestions).
+ Make sure that the sdcc program is in the bin folder, if not perhaps something
+ did not install correctly.
+\newline 

 
 

+\newline 

 
 \series medium 
 
 \series medium 

-Holds common C header files
+SDCC 
+\series default 
+is commonly installed as described in section 
+\begin_inset Quotes sld

 \end_inset 
 \end_inset 

-</cell>
-</row>
-</lyxtabular>

 
 

+Install and search paths
+\begin_inset Quotes srd

 \end_inset 
 
 
 \end_inset 
 
 


@@ -920,7 +2136,11 @@ Holds common C header files
 
 \series medium 
 Make sure the compiler works on a very simple example.
 
 \series medium 
 Make sure the compiler works on a very simple example.

- Type in the following test.c program using your favorite editor:
+ Type in the following test.c program using your favorite 
+\series default 
+ascii 
+\series medium 
+editor:

 \series default 
 
 \newline 
 \series default 
 
 \newline 


@@ -1068,9 +2288,11 @@ A thing to try is starting from scratch by unpacking the .tgz source package
 
 \newline 
 
 
 \newline 
 

-\family typewriter 
+\family sans 
+\series bold 

 ./configure 2>&1 | tee configure.log
 \family default 
 ./configure 2>&1 | tee configure.log
 \family default 

+\series default 

 
 \newline 
 
 
 \newline 
 


@@ -1080,9 +2302,11 @@ and build it like:
 
 \newline 
 
 
 \newline 
 

-\family typewriter 
+\family sans 
+\series bold 

 make 2>&1 | tee make.log
 \family default 
 make 2>&1 | tee make.log
 \family default 

+\series default 

 
 \newline 
 
 
 \newline 
 


@@ -1143,67 +2367,19 @@ make install
  command does.
 \layout Standard
 
  command does.
 \layout Standard
 

-This will install the compiler, other executables and libraries in to the
- appropriate system directories.
- The default is to copy the executables to /usr/local/bin and the libraries
- and header files to /usr/local/share/sdcc/lib and /usr/local/share/sdcc/include.
- On most systems you will need super-user privilages to do this.
-\layout Subsection
-
-Advanced Install Options
-\layout Standard
-
-The 
-\begin_inset Quotes eld
-\end_inset 
-
-configure
-\begin_inset Quotes erd
-\end_inset 
-
- command has several options.
- The most commonly used option is ---prefix=<directory name>, where <directory
- name> is the final location for the sdcc executables and libraries, (default
- location is /usr/local).
- The installation process will create the following directory structure
- under the <directory name> specified (if they do not already exist).
- 
-\newline 
-
-\newline 
-bin/ - binary exectables (add to PATH environment variable)
-\newline 
-bin/share/
-\newline 
-bin/share/sdcc/include/ - include header files
-\newline 
-bin/share/sdcc/lib/
-\newline 
-bin/share/sdcc/lib/small/ - Object & library files for small model library
-\newline 
-bin/share/sdcc/lib/large/ - Object & library files for large model library
-\newline 
-bin/share/sdcc/lib/ds390/ - Object & library files for DS80C390 library
-\newline 
-bin/share/sdcc/lib/z80/ - Object & library files for Z80 library
-\newline 
-
-\newline 
-The command 
-\family sans 
-\series bold 
-
+This will install the compiler, other executables libraries and include
+ files in to the appropriate directories.
+ See section 

 \begin_inset Quotes sld
 \end_inset 
 
 \begin_inset Quotes sld
 \end_inset 
 

-./configure ---prefix=/usr/local
-\begin_inset Quotes erd
+Install and Search PATHS
+\begin_inset Quotes srd

 \end_inset 
 
 \end_inset 
 

- 
-\family default 
-\series default 
-will configure the compiler to be installed in directory /usr/local.
+.
+\newline 
+On most systems you will need super-user privilages to do this.

 \layout Subsection
 
 Components of SDCC
 \layout Subsection
 
 Components of SDCC


@@ -1220,7 +2396,7 @@ SDCC is not just a compiler, but a collection of tools by various developers.
 
 \newline 
 You might want to look at the files which are installed in <installdir>.
 
 \newline 
 You might want to look at the files which are installed in <installdir>.

- At the time of this writing, we find the following programs:
+ At the time of this writing, we find the following programs for gcc-builds:

 \newline 
  
 \newline 
 \newline 
  
 \newline 


@@ -1271,8 +2447,8 @@ the include files
 In <installdir>/share/sdcc/lib
 \layout Itemize
 
 In <installdir>/share/sdcc/lib
 \layout Itemize
 

-the sources of the runtime library and the subdirs small large and ds390
- with the precompiled relocatables.
+the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
+ relocatables.

 \layout Standard
 
 In <installdir>/share/sdcc/doc
 \layout Standard
 
 In <installdir>/share/sdcc/doc


@@ -1336,7 +2512,7 @@ sdcdb - Source Level Debugger
 
 \family typewriter 
 \shape italic 
 
 \family typewriter 
 \shape italic 

-<todo: is this thing alive?>
+<todo: is this thing still alive?>

 \newline 
 
 \newline 
 \newline 
 
 \newline 


@@ -1388,7 +2564,16 @@ sourcefile.ihx - The load module in Intel hex format (you can select the
 \newline 
 sourcefile.cdb - An optional file (with ---debug) containing debug information
 \newline 
 \newline 
 sourcefile.cdb - An optional file (with ---debug) containing debug information
 \newline 

+sourcefile.dump* - Dump file to debug the compiler it self (with ---dumpall)
+ (see section 
+\begin_inset Quotes sld
+\end_inset 
+
+Anatomy of the compiler
+\begin_inset Quotes srd
+\end_inset 

 
 

+).

 \layout Subsubsection
 
 Projects with Multiple Source Files
 \layout Subsubsection
 
 Projects with Multiple Source Files


@@ -1779,16 +2964,6 @@ Linker Options
 \labelwidthstring 00.00.0000
 
 
 \labelwidthstring 00.00.0000
 
 

-\series bold 
--o\SpecialChar ~
-<path/file> 
-\series default 
-the output path resp.
- file where everything will be placed
-\layout List
-\labelwidthstring 00.00.0000
-
-

 \series bold 
 -L\SpecialChar ~
 ---lib-path
 \series bold 
 -L\SpecialChar ~
 ---lib-path


@@ -2061,12 +3236,20 @@ Will not do loop reversal optimization.
 \layout List
 \labelwidthstring 00.00.0000
 
 \layout List
 \labelwidthstring 00.00.0000
 

+---
+\series bold 
+nolabelopt
+\series default 
+ Will not optimize labels (makes the dumpfiles more readable).
+\layout List
+\labelwidthstring 00.00.0000
+

 
 \series bold 
 ---no-xinit-opt
 \series default 
 
 \series bold 
 ---no-xinit-opt
 \series default 

- This will disable the memcpy of initialized data in far space from code
- space
+ Will not memcpy initialized data in far space from code space.
+ This saves a few bytes in code space if you don't have initialized data.

 \layout Subsubsection
 
 Other Options
 \layout Subsubsection
 
 Other Options


@@ -2083,6 +3266,15 @@ Other Options
 \labelwidthstring 00.00.0000
 
 
 \labelwidthstring 00.00.0000
 
 

+\series bold 
+--c1mode
+\series default 
+ reads the preprocessed source from standard input and compiles it.
+ The file name for the assembler output must be specified using the -o option.
+\layout List
+\labelwidthstring 00.00.0000
+
+

 \series bold 
 -E
 \series default 
 \series bold 
 -E
 \series default 


@@ -2093,6 +3285,19 @@ Other Options
 \labelwidthstring 00.00.0000
 
 
 \labelwidthstring 00.00.0000
 
 

+\series bold 
+-o\SpecialChar ~
+<path/file> 
+\series default 
+The output path resp.
+ file where everything will be placed.
+ If the parameter is a path, it must have a trailing slash (or backslash
+ for the Windows binaries) to be recognized as a path.
+ 
+\layout List
+\labelwidthstring 00.00.0000
+
+

 \series bold 
 ---stack-auto
 \series default 
 \series bold 
 ---stack-auto
 \series default 


@@ -2352,6 +3557,33 @@ cyclomatic complexity
 -V
 \series default 
  Shows the actual commands the compiler is executing.
 -V
 \series default 
  Shows the actual commands the compiler is executing.

+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold 
+---no-c-code-in-asm
+\series default 
+ Hides your ugly and inefficient c-code from the asm file, so you can always
+ blame the compiler :).
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold 
+---i-code-in-asm
+\series default 
+ Include i-codes in the asm file.
+ Sounds like noise but is most helpfull for debugging the compiler itself.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold 
+---less-pedantic
+\series default 
+ Disable some of the more pedantic warnings (jwk burps: please be more specific
+ here, please!)

 \layout Subsubsection
 
 Intermediate Dump Options
 \layout Subsubsection
 
 Intermediate Dump Options


@@ -2474,6 +3706,90 @@ Will create a dump of iCode's, after register assignment, into a file named
 Will cause all the above mentioned dumps to be created.
 \layout Subsection
 
 Will cause all the above mentioned dumps to be created.
 \layout Subsection
 

+Environment variables
+\layout Standard
+
+SDCC recognizes the following environment variables:
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold 
+SDCC_LEAVE_SIGNALS
+\series default 
+ SDCC installs a signal handler to be able to delete temporary files after
+ an user break (^C) or an exception.
+ If this environment variable is set, SDCC won't install the signal handler
+ in order to be able to debug SDCC.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold 
+TMP,\SpecialChar ~
+TEMP,\SpecialChar ~
+TMPDIR
+\series default 
+ Path, where temporary files will be created.
+ The order of the variables is the search order.
+ In a standard *nix environment these variables are not set, and there's
+ no need to set them.
+ On Windows it's recommended to set one of them.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold 
+SDCC_HOME
+\series default 
+ Path, see 
+\begin_inset Quotes sld
+\end_inset 
+
+2.3 Install and search paths
+\begin_inset Quotes srd
+\end_inset 
+
+.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold 
+SDCC_INCLUDE
+\series default 
+ Path, see 
+\begin_inset Quotes sld
+\end_inset 
+
+2.3 Install and search paths
+\begin_inset Quotes srd
+\end_inset 
+
+.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold 
+SDCC_LIB
+\series default 
+ Path, see 
+\begin_inset Quotes sld
+\end_inset 
+
+2.3 Install and search paths
+\begin_inset Quotes srd
+\end_inset 
+
+.
+\layout Standard
+
+There are some more environment variables recognized by SDCC, but these
+ are solely used for debugging purposes.
+ They can change or disappear very quickly, and will never be documentated.
+\layout Subsection
+

 MCS51/DS390 Storage Class Language Extensions
 \layout Standard
 
 MCS51/DS390 Storage Class Language Extensions
 \layout Standard
 


@@ -2958,9 +4274,9 @@ Interrupt Numbers and the corresponding address & descriptions for the Standard
 \begin_inset  Tabular
 <lyxtabular version="3" rows="6" columns="3">
 <features>
 \begin_inset  Tabular
 <lyxtabular version="3" rows="6" columns="3">
 <features>

-<column alignment="center" valignment="top" leftline="true" width="0(null)">
-<column alignment="center" valignment="top" leftline="true" width="0(null)">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
+<column alignment="center" valignment="top" leftline="true" width="0in">
+<column alignment="center" valignment="top" leftline="true" width="0in">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">

 <row topline="true" bottomline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 <row topline="true" bottomline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text


@@ -3821,7 +5137,7 @@ The same goes the other way, ie.
  labels defines in inline assembly CANNOT be accessed by C statements.
 \layout Subsection
 
  labels defines in inline assembly CANNOT be accessed by C statements.
 \layout Subsection
 

-int(16 bit) and long (32 bit) Support
+int (16 bit) and long (32 bit) Support

 \layout Standard
 
 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
 \layout Standard
 
 For signed & unsigned int (16 bit) and long (32 bit) variables, division,


@@ -5538,15 +6854,15 @@ Pragmas
 \layout Standard
 
 SDCC supports the following #pragma directives.
 \layout Standard
 
 SDCC supports the following #pragma directives.

- This directives are applicable only at a function level.

 \layout Itemize
 
 SAVE - this will save all the current options.
 \layout Itemize
 
 RESTORE - will restore the saved options from the last save.
 \layout Itemize
 
 SAVE - this will save all the current options.
 \layout Itemize
 
 RESTORE - will restore the saved options from the last save.

- Note that SAVES & RESTOREs cannot be nested.
+ Note that SAVEs & RESTOREs cannot be nested.

  SDCC uses the same buffer to save the options each time a SAVE is called.
  SDCC uses the same buffer to save the options each time a SAVE is called.

+ (jwk burps: either fix that or throw a warning)

 \layout Itemize
 
 NOGCSE - will stop global subexpression elimination.
 \layout Itemize
 
 NOGCSE - will stop global subexpression elimination.


@@ -5563,6 +6879,10 @@ NOOVERLAY - the compiler will not overlay the parameters and local variables
  of a function.
 \layout Itemize
 
  of a function.
 \layout Itemize
 

+LESS_PEDANTIC - the compiler will not warn you anymore for obvious mistakes,
+ you'r on your own now ;-(
+\layout Itemize
+

 NOLOOPREVERSE - Will not do loop reversal optimization
 \layout Itemize
 
 NOLOOPREVERSE - Will not do loop reversal optimization
 \layout Itemize
 


@@ -6258,7 +7578,7 @@ Here are a few guidelines that will help the compiler generate more efficient
 
 Use the smallest data type to represent your data-value.
  If it is known in advance that the value is going to be less than 256 then
 
 Use the smallest data type to represent your data-value.
  If it is known in advance that the value is going to be less than 256 then

- use a 'char' instead of a 'short' or 'int'.
+ use an 'unsigned char' instead of a 'short' or 'int'.

 \layout Itemize
 
 Use unsigned when it is known in advance that the value is not going to
 \layout Itemize
 
 Use unsigned when it is known in advance that the value is not going to


@@ -6273,8 +7593,8 @@ Declare the variables to be local whenever possible, especially loop control
  variables (induction).
 \layout Itemize
 
  variables (induction).
 \layout Itemize
 

-Since the compiler does not do implicit integral promotion, the programmer
- should do an explicit cast when integral promotion is required.
+Since the compiler does not always do implicit integral promotion, the programme
+r should do an explicit cast when integral promotion is required.

 \layout Itemize
 
 Reducing the size of division, multiplication & modulus operations can reduce
 \layout Itemize
 
 Reducing the size of division, multiplication & modulus operations can reduce


@@ -7608,6 +8928,9 @@ cc@sdcc.sourceforge.net'.
  in locating optimization problems.
 \layout Section
 
  in locating optimization problems.
 \layout Section
 

+Compiler internals
+\layout Subsection
+

 The anatomy of the compiler
 \layout Standard
 
 The anatomy of the compiler
 \layout Standard
 


@@ -7975,12 +9298,7 @@ Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{in
 
 \size footnotesize 
 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
 
 \size footnotesize 
 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near

- * int}[r0] + 
-\layout Standard
-
-
-\size footnotesize 
-0x2 {short}
+ * int}[r0] + 0x2 {short}

 \layout Standard
 
 
 \layout Standard
 
 


@@ -8042,12 +9360,7 @@ Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
 
 \size footnotesize 
 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
 
 \size footnotesize 
 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]

- + 
-\layout Standard
-
-
-\size footnotesize 
-ITemp21 [lr21:38]{short}[r4]
+ + ITemp21 [lr21:38]{short}[r4]

 \layout Standard
 
 
 \layout Standard
 
 


@@ -8059,12 +9372,7 @@ Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
 
 \size footnotesize 
 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
 
 \size footnotesize 
 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]

- + 
-\layout Standard
-
-
-\size footnotesize 
-iTemp15 [lr29:30]{short}[r1]
+ + iTemp15 [lr29:30]{short}[r1]

 \layout Standard
 
 
 \layout Standard
 
 


@@ -8104,27 +9412,22 @@ Sample.c(19:39:48:0)_forbreak_0($7) :
 
 \size footnotesize 
 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
 
 \size footnotesize 
 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]

- + 
+ + ITemp11 [lr19:40]{short}[r3]

 \layout Standard
 
 
 \size footnotesize 
 \layout Standard
 
 
 \size footnotesize 

-ITemp11 [lr19:40]{short}[r3]
+Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}

 \layout Standard
 
 
 \size footnotesize 
 \layout Standard
 
 
 \size footnotesize 

-sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
+Sample.c(20:42:51:0)_return($8) :

 \layout Standard
 
 
 \size footnotesize 
 \layout Standard
 
 
 \size footnotesize 

-sample.c(20:42:51:0)_return($8) :
-\layout Standard
-
-
-\size footnotesize 
-sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
+Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}

 \size default 
 
 \newline 
 \size default 
 
 \newline 


@@ -8880,10 +10183,53 @@ mov dpl,a
 \SpecialChar ~
 \SpecialChar ~
 ret
 \SpecialChar ~
 \SpecialChar ~
 ret

-\size default 
+\newline 
+
+\layout Subsection
+
+A few words about basic block successors, predecessors and dominators
+\layout Standard
+
+Successors are basic blocks that might execute after this basic block.
+\newline 
+Predecessors are basic blocks that might execute before reaching this basic
+ block.
+\newline 
+Dominators are basic blocks that WILL execute before reaching this basic
+ block.
+\newline 
+
+\layout Standard

 
 

+[basic block 1]
+\layout Standard
+
+if (something)
+\layout Standard
+
+[basic block 2]
+\layout Standard
+
+else
+\layout Standard
+
+[basic block 3]
+\layout Standard
+
+[basic block 4]

 \newline 
 
 \newline 
 

+\layout Standard
+
+a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
+\layout Standard
+
+b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
+\layout Standard
+
+c) domVect of [BB4] = BB1 ...
+ here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
+ was executed.

 \layout Section
 
 Acknowledgments
 \layout Section
 
 Acknowledgments