sdccman.txt

This a FREE tool chain which compiles C codes into 8051 binary code, converts the binary to RTL ROM,

then be further optimized, or hand coded in assembly if 
needed. 

SDCC also comes with a companion source level 
debugger SDCDB. The debugger currently uses ucSim, a 
free open source simulator for 8051 and other micro-controllers.


The latest SDCC version can be downloaded from [http://sdcc.sourceforge.net/snap.php]. Please 
note: the compiler will probably always be some steps 
ahead of this documentation

Obviously this has pros and cons
.

1.2 Open Source

All packages used in this compiler system are open 
source and freeware; source code for all the 
sub-packages (pre-processor, assemblers, linkers etc.) 
is distributed with the package. This documentation is 
maintained using a free open source word processor (LyX).

This program is free software; you can redistribute it 
and/or modify it under the terms of the GNU General 
Public License as published by the Free Software 
Foundation; either version 2, or (at your option) any 
later version. This program is distributed in the hope 
that it will be useful, but WITHOUT ANY WARRANTY; 
without even the implied warranty of MERCHANTABILITY or 
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General 
Public License for more details. You should have 
received a copy of the GNU General Public License along 
with this program; if not, write to the Free Software 
Foundation, 59 Temple Place - Suite 330, Boston, MA 
02111-1307, USA. In other words, you are welcome to 
use, share and improve this program. You are forbidden 
to forbid anyone else to use, share and improve what 
you give them. Help stamp out software-hoarding! 

1.3 Typographic conventions

Throughout this manual, we will use the following 
convention. Commands you have to type in are printed in 
"sans serif". Code samples are printed in typewriter 
font. Interesting items and new terms are printed in italic.

1.4 Compatibility<sec:Compatibility-with-previous> with previous versions

Newer versions have usually numerous bug fixes compared 
with the previous version. But we also sometimes 
introduce some incompatibilities with older versions. 
Not just for the fun of it, but to make the compiler 
more stable, efficient and ANSI compliant (see section [sub:ANSI-Compliance] 
for ANSI-Compliance). 


* short is now equivalent to int (16 bits), it used to 
  be equivalent to char (8 bits) which is not ANSI 
  compliant. To maintain compatibility, old programs 
  may be compiled using the --short-is-8bits 
  commandline option (see [lyx:--short-is-8bits]).

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

* char type parameters to vararg functions are casted 
  to int unless explicitly casted and --std-c89 and --std-c99
   command line option are not defined 

 !
  , e.g.: 
  char a=3;
  printf ("%d %c\n", a, (char)a);
 will 
  push a as an int and as a char resp if --std-c89 and --std-c99
   command line options are not defined,
 will push a as 
  two ints if --std-c89 or --std-c99 command line 
  option is defined.

* option --regextend has been removed.

* option --noregparms has been removed.

* option --stack-after-data has been removed.

* bit and sbit types now consistently behave like the 
  C99 _Bool type with respect to type conversion. The 
  most common incompatibility resulting from this 
  change is related to bit toggling idioms, e.g.:
  bit b;
  
  b = ~b; /* equivalent to b=1 instead of toggling b */

 !
  
  b = !b; /* toggles b */
In previous versions, both 
  forms would have toggled the bit.

* in older versions, the preprocessor was always called 
  with -std=c99 regardless of the --std-xxx setting. 
  This is no longer true, and can cause compilation 
  failures on code built with --std-c89 but using c99 
  preprocessor features, such as one-line (//) comments

<pending: more incompatibilities?>

1.5 System Requirements

What do you need before you start installation of SDCC? 
A computer, and a desire to compute. The preferred 
method of installation is to compile SDCC from source 
using GNU gcc and make. For Windows some pre-compiled 
binary distributions are available for your 
convenience. You should have some experience with 
command line tools and compiler use.

1.6 Other Resources

The SDCC home page at [http://sdcc.sourceforge.net/] is a great place to find 
distribution sets. You can also find links to the user 
mailing lists that offer help or discuss SDCC with 
other SDCC users. Web links to other SDCC related sites 
can also be found here. This document can be found in 
the DOC directory of the source package as a text or 
HTML file. A pdf version of this document is available 
at [http://sdcc.sourceforge.net/doc/sdccman.pdf]. Some of the other tools (simulator and assembler) 
included with SDCC contain their own documentation and 
can be found in the source distribution. If you want 
the latest unreleased software, the complete source 
package is available directly from Subversion on 
https://sdcc.svn.sourceforge.net/svnroot/sdcc/trunk/sdcc.

1.7 Wishes for the future

There are (and always will be) some things that could 
be done. Here are some I can think of:


char KernelFunction3(char p) at 0x340;


better code banking support for mcs51

If you can think 
of some more, please see the section [sub:Requesting-Features] about filing 
feature requests.


Installing SDCC

For most users it is sufficient to skip to either 
section [sub:Building-SDCC-on-Linux] (Unix) or section [sub:Windows-Install] (Windows). More detailed 
instructions follow below.

2.1 Configure Options

The install paths, search paths and other options are 
defined when running 'configure'. The defaults can be 
overridden by:

--prefix see table below

--exec_prefix see table below

--bindir see table below

--datadir see table below

--datarootdir see table below


  docdir environment variable, see table below

  include_dir_suffix environment variable, see table below

  lib_dir_suffix environment variable, see table below

  sdccconf_h_dir_separator environment variable, either / 
or \\ makes sense here. This character will only be 
used in sdccconf.h; don't forget it's a C-header, 
therefore a double-backslash is needed there.


--disable-mcs51-port Excludes the Intel mcs51 port

--disable-gbz80-port Excludes the Gameboy gbz80 port

--disable-z80-port Excludes the z80 port

--disable-avr-port Excludes the AVR port

--disable-ds390-port Excludes the DS390 port

--disable-hc08-port Excludes the HC08 port

--disable-pic-port Excludes the PIC14 port

--disable-pic16-port Excludes the PIC16 port

--disable-xa51-port Excludes the XA51 port

--disable-ucsim Disables configuring and building of ucsim

--disable-device-lib Disables automatically building 
device libraries

--disable-packihx Disables building packihx


--enable-doc Build pdf, html and txt files from the lyx sources

--enable-libgc Use the Bohem memory allocator. Lower 
runtime footprint.

Furthermore the environment variables CC, CFLAGS, ... 
the tools and their arguments can be influenced. Please 
see `configure --help' and the man/info pages of 
`configure' for details.

The names of the standard 
libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB, 
STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the 
environment variables SDCC_DIR_NAME, SDCC_INCLUDE_NAME, 
SDCC_LIB_NAME are defined by `configure' too. At the 
moment it's not possible to change the default settings 
(it was simply never required).

These configure options 
are compiled into the binaries, and can only be changed 
by rerunning 'configure' and recompiling SDCC. The 
configure options are written in italics to distinguish 
them from run time environment variables (see section 
search paths).

The settings for "Win32 builds" are used by 
the SDCC team to build the official Win32 binaries. The 
SDCC team uses Mingw32 to build the official Windows 
binaries, because it's

1. open source, 

2. a gcc compiler and last but not least

3. the binaries can be built by cross compiling on SDCC 
  Distributed Compile Farm.

See the examples, how to pass the Win32 settings to 
'configure'. The other Win32 builds using Borland, VC 
or whatever don't use 'configure', but a header file 
sdcc_vc_in.h is the same as sdccconf.h built by 
'configure' for Win32.

These defaults are:


+-----------------------+--------------------------+--------------------+
| 

Variable            | 

default                | 

Win32 builds     |
+-----------------------+--------------------------+--------------------+
+-----------------------+--------------------------+--------------------+
| 

PREFIX              | 

/usr/local             | 

\sdcc            |
+-----------------------+--------------------------+--------------------+
| 

EXEC_PREFIX         | 

$PREFIX                | 

$PREFIX          |
+-----------------------+--------------------------+--------------------+
| 

BINDIR              | 

$EXEC_PREFIX/bin       | 

$EXEC_PREFIX\bin |
+-----------------------+--------------------------+--------------------+
| 

DATADIR             | 

$DATAROOTDIR           | 

$DATAROOTDIR     |
+-----------------------+--------------------------+--------------------+
| 

DATAROOTDIR         | 

$PREFIX/share          | 

$PREFIX          |
+-----------------------+--------------------------+--------------------+
| 

DOCDIR              | 

$DATAROOTDIR/sdcc/doc  | 

$DATAROOTDIR\doc |
+-----------------------+--------------------------+--------------------+
| 

INCLUDE_DIR_SUFFIX  | 

sdcc/include           | 

include          |
+-----------------------+--------------------------+--------------------+
| 

LIB_DIR_SUFFIX      | 

sdcc/lib               | 

lib              |
+-----------------------+--------------------------+--------------------+



'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):

 

+------------------------+---------------+----------------+
| 

Variable (computed)  | 

default     | 

Win32 builds |
+------------------------+---------------+----------------+
+------------------------+---------------+----------------+
| 

BIN2DATA_DIR         | 

../share    | 

..           |
+------------------------+---------------+----------------+
| 

PREFIX2BIN_DIR       | 

bin         | 

bin          |
+------------------------+---------------+----------------+
| 

PREFIX2DATA_DIR      | 

share/sdcc  | 

             |
+------------------------+---------------+----------------+



Examples:

./configure
./configure --prefix="/usr/bin" --datarootdir="/usr/share"

./configure --disable-avr-port --disable-xa51-port

To cross compile on linux for Mingw32 (see also 
'sdcc/support/scripts/sdcc_mingw32'):

./configure \
CC="i586-mingw32msvc-gcc" CXX="i586-mingw32msvc-g++"
 \ 
RANLIB="i586-mingw32msvc-ranlib" \
STRIP="i586-mingw32msvc-strip"
 \
--prefix="/sdcc" \
--datarootdir="/sdcc" \
docdir="\${datarootdir}/doc"
 \
include_dir_suffix="include" \
lib_dir_suffix="lib" \

sdccconf_h_dir_separator="\\\\" \
--disable-device-lib\
-
-host=i586-mingw32msvc\
--build=unknown-unknown-linux-gnu

To "cross"compile on Cygwin for Mingw32 (see also 
sdcc/support/scripts/sdcc_cygwin_mingw32):

./configure -C \
--prefix="/sdcc" \
--datarootdir="/sdcc" \