X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=doc%2Fsdccman.lyx;h=651e1db2bcd2d0099c57a98c92dac4224b0edc42;hb=19eb37fd0abc83f9e2491a3f9ac2033363954852;hp=4fc1f3d995ce2c4de72dd9fab3b00b431f1c88fa;hpb=04704b10209343721b13aea3aaa12f6a654ea872;p=fw%2Fsdcc diff --git a/doc/sdccman.lyx b/doc/sdccman.lyx index 4fc1f3d9..651e1db2 100644 --- a/doc/sdccman.lyx +++ b/doc/sdccman.lyx @@ -24,6 +24,11 @@ \papersides 1 \paperpagestyle fancy +\layout Comment + +Please note: double dashed longoptions (e.g. + --version) need three dashes in this document to be visable in html and + pdf output. \layout Title SDCC Compiler User Guide @@ -128,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. @@ -143,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 @@ -221,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 @@ -275,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 @@ -387,12 +392,16 @@ 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 -- path(arv[0])/../include and then /sdcc/include (windoze msvc and borland - builds) +- path(arv[0])/../include and then /sdcc/include (as a last resort for windoze + msvc and borland builds) \layout Enumerate Library files (the @@ -446,7 +455,7 @@ model \shape italic model \shape default - (windoze msvc and borland builds) + (as a last resort for windoze msvc and borland builds) \layout Enumerate Documentation (although never really searched for, you have to do that yourself @@ -468,7 +477,9 @@ 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) @@ -788,12 +799,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 - +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 @@ -820,92 +868,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: +SDCC \series default - -\newline - -\newline - -\begin_inset Tabular - - - - - - -\begin_inset Text - -\layout Standard - -/ -\series medium -usr/local/bin -\end_inset - - -\begin_inset Text - -\layout Standard - - -\series medium -Holds executables(sdcc, s51, aslink, -\series default -... -\series medium -) -\end_inset - - - - -\begin_inset Text - -\layout Standard - -/ -\series medium -usr/local/share/sdcc/lib -\end_inset - - -\begin_inset Text - -\layout Standard - - -\series medium -Holds common C -\series default -libraries -\end_inset - - - - -\begin_inset Text - -\layout Standard - -/ -\series medium -usr/local/share/sdcc/include -\end_inset - - -\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 - - - +Install and search paths +\begin_inset Quotes srd \end_inset @@ -915,7 +885,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 @@ -1063,9 +1037,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 @@ -1075,9 +1051,11 @@ and build it like: \newline -\family typewriter +\family sans +\series bold make 2>&1 | tee make.log \family default +\series default \newline @@ -1138,67 +1116,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=, where 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 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 @@ -1215,7 +1145,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 . - 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 @@ -1266,8 +1196,8 @@ the include files In /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 /share/sdcc/doc @@ -1331,7 +1261,7 @@ sdcdb - Source Level Debugger \family typewriter \shape italic - + \newline \newline @@ -1383,7 +1313,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 @@ -5570,6 +5509,14 @@ EXCLUDE\SpecialChar ~ none. \layout Itemize +NOIV - Do not generate interrupt vector table entries for all ISR functions + defined after the pragma. + This is useful in cases where the interrupt vector table must be defined + manually, or when there is a secondary, manually defined interrupt vector + table (e.g. + for the autovector feature of the Cypress EZ-USB FX2). +\layout Itemize + CALLEE-SAVES function1[,function2[,function3...]] - The compiler by default uses a caller saves convention for register saving across function calls, however this can cause unneccessary register pushing & popping when calling @@ -6245,7 +6192,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 @@ -6260,8 +6207,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 @@ -7962,12 +7909,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 @@ -8029,12 +7971,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 @@ -8046,12 +7983,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 @@ -8091,27 +8023,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