* src/SDCCglue.h: make tmpfileNameSet available for preOutName
[fw/sdcc] / doc / sdccman.lyx
index 509b48a6f8928b26f8dbede867708c16d2f611a2..b961c03f6b1b3112e83bb261fbd9fb75c89b3a53 100644 (file)
@@ -26,7 +26,7 @@
 
 \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
@@ -133,7 +133,7 @@ inline assembler code
 \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.
@@ -148,7 +148,7 @@ SDCC also comes with a companion source level debugger SDCDB, the debugger
 
 \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 
 
@@ -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
 
-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
@@ -280,7 +280,7 @@ Other Resources
 \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 
 
@@ -333,7 +333,7 @@ Installation
 Install and search paths
 \layout Standard
 
-Linux (and other gcc-builds like Solaris, Cygwin, Mingw and OSX) by default
+Linux (and other gcc-builds like Solaris, Cygwin, Mingw32 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.
@@ -392,7 +392,11 @@ SDCC_INCLUDE_PATH
 \begin_inset Quotes sld
 \end_inset 
 
-SDCCHOME)/include
+SDCCHOME
+\begin_inset Quotes srd
+\end_inset 
+
+)/include
 \newline 
 - /usr/local/share/sdcc/include (gcc builds)
 \newline 
@@ -473,10 +477,12 @@ SDCCHOME
 \layout Standard
 
 So, for windoze it is highly recommended to set the environment variable
- SDCCHOME to prevent needless usage of -I and -L.
+ SDCCHOME to prevent needless usage of -I and -L options.
+ For gcc-builds SDCCHOME should only be set when sdcc is installed in non-standa
+rd paths.
 \layout Subsection
 
-Linux and other gcc-based systems (cygwin, mingw, osx)
+Linux and other gcc-based systems (cygwin, mingw32, osx)
 \layout Enumerate
 
 
@@ -577,7 +583,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.
- 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 
@@ -610,7 +617,7 @@ Adjust your environment variable PATH to include the location of the bin
  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 
@@ -793,12 +800,49 @@ bin_vc to sdcc
 bin, and you can compile using sdcc.
 \layout Subsubsection
 
-Windows Install Using Borland ......
-\layout Standard
+Windows Install Using Borland
+\layout Enumerate
 
+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
 
-\shape italic 
-<pending>
+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 
+
+\family sans 
+\series bold 
+find .
+\backslash 
+( -name '*.obj' -o -name '*.lib' -o -name '*.rul' 
+\backslash 
+) -print -exec rm {} 
+\backslash 
+;
+\family default 
+\series default 
+
+\newline 
+
+\newline 
+or on Windows NT/2000/XP from the command prompt with the commmand:
+\newline 
+
+\family sans 
+\series bold 
+
+\newline 
+del /s *.obj *.lib *.rul
+\family default 
+\series default 
+ from the sdcc directory.
 \layout Subsection
 
 Testing out the SDCC Compiler
@@ -825,92 +869,14 @@ The first thing you should do after installing your SDCC compiler is to
 \newline 
 
 \series medium 
-SDCC binaries are commonly installed in a directory arrangement like this:
-\series default 
-
-\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
-
-\layout Standard
-
-
-\series medium 
-Holds common C 
+SDCC 
 \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
-
-\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
-
-
-\series medium 
-Holds common C header files
+is commonly installed as described in section 
+\begin_inset Quotes sld
 \end_inset 
-</cell>
-</row>
-</lyxtabular>
 
+Install and search paths
+\begin_inset Quotes srd
 \end_inset 
 
 
@@ -920,7 +886,11 @@ Holds common C header files
 
 \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 
@@ -1068,9 +1038,11 @@ A thing to try is starting from scratch by unpacking the .tgz source package
 
 \newline 
 
-\family typewriter 
+\family sans 
+\series bold 
 ./configure 2>&1 | tee configure.log
 \family default 
+\series default 
 
 \newline 
 
@@ -1080,9 +1052,11 @@ and build it like:
 
 \newline 
 
-\family typewriter 
+\family sans 
+\series bold 
 make 2>&1 | tee make.log
 \family default 
+\series default 
 
 \newline 
 
@@ -1143,67 +1117,19 @@ make install
  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 
 
-./configure ---prefix=/usr/local
-\begin_inset Quotes erd
+Install and Search PATHS
+\begin_inset Quotes srd
 \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
@@ -1220,7 +1146,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>.
- 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 
@@ -1271,8 +1197,8 @@ the include files
 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
@@ -1336,7 +1262,7 @@ sdcdb - Source Level Debugger
 
 \family typewriter 
 \shape italic 
-<todo: is this thing alive?>
+<todo: is this thing still alive?>
 \newline 
 
 \newline 
@@ -1388,7 +1314,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 
+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
@@ -1779,16 +1714,6 @@ Linker Options
 \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
@@ -2083,6 +2008,15 @@ Other Options
 \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 
@@ -2093,6 +2027,19 @@ Other Options
 \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 
@@ -2352,6 +2299,24 @@ cyclomatic complexity
 -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.
+ Looks like noise but is most helpfull for debugging the compiler itself.
 \layout Subsubsection
 
 Intermediate Dump Options
@@ -2474,6 +2439,116 @@ 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
 
+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 
+(coming\SpecialChar ~
+soon:\SpecialChar ~
+SDCC_BIN_PATH)
+\series default 
+ Path, see 
+\begin_inset Quotes sld
+\end_inset 
+
+2.1 Install and search paths
+\begin_inset Quotes srd
+\end_inset 
+
+.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold 
+(coming\SpecialChar ~
+soon:\SpecialChar ~
+SDCC_INCLUDE_PATH)
+\series default 
+ Path, see 
+\begin_inset Quotes sld
+\end_inset 
+
+2.1 Install and search paths
+\begin_inset Quotes srd
+\end_inset 
+
+.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold 
+(coming\SpecialChar ~
+soon:\SpecialChar ~
+SDCC_LIB_PATH)
+\series default 
+ Path, see 
+\begin_inset Quotes sld
+\end_inset 
+
+2.1 Install and search paths
+\begin_inset Quotes srd
+\end_inset 
+
+.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold 
+SDCCDIR\SpecialChar ~
+(soon\SpecialChar ~
+replaced\SpecialChar ~
+by:\SpecialChar ~
+SDCCPATH)
+\series default 
+ Path, see 
+\begin_inset Quotes sld
+\end_inset 
+
+2.1 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
 
@@ -2958,9 +3033,9 @@ Interrupt Numbers and the corresponding address & descriptions for the Standard
 \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="0pt">
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
 <row topline="true" bottomline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
@@ -3821,7 +3896,7 @@ The same goes the other way, ie.
  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,
@@ -6258,7 +6333,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 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
@@ -6273,8 +6348,8 @@ Declare the variables to be local whenever possible, especially loop control
  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
@@ -7975,12 +8050,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
- * int}[r0] + 
-\layout Standard
-
-
-\size footnotesize 
-0x2 {short}
+ * int}[r0] + 0x2 {short}
 \layout Standard
 
 
@@ -8042,12 +8112,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]
- + 
-\layout Standard
-
-
-\size footnotesize 
-ITemp21 [lr21:38]{short}[r4]
+ + ITemp21 [lr21:38]{short}[r4]
 \layout Standard
 
 
@@ -8059,12 +8124,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]
- + 
-\layout Standard
-
-
-\size footnotesize 
-iTemp15 [lr29:30]{short}[r1]
+ + iTemp15 [lr29:30]{short}[r1]
 \layout Standard
 
 
@@ -8104,27 +8164,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]
- + 
-\layout Standard
-
-
-\size footnotesize 
-ITemp11 [lr19:40]{short}[r3]
+ + ITemp11 [lr19:40]{short}[r3]
 \layout Standard
 
 
 \size footnotesize 
-sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
+Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
 \layout Standard
 
 
 \size footnotesize 
-sample.c(20:42:51:0)_return($8) :
+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