sdccman.txt

很少见的源码公开的msc51和z80的c编译器。

+--------------------------------+-------------------------------------------+


Make sure the compiler works on a very simple example. Type
in the following test.c program using your favorite editor:

int test(int t) {
    return t+3;
}

Compile this using the following command: "sdcc -c test.c".
If all goes well, the compiler will generate a test.asm
and test.rel file. Congratulations, you've just compiled
your first program with SDCC. We used the -c option to tell
SDCC not to link the generated code, just to keep things
simple for this step.

The next step is to try it with the linker. Type in "sdcc
test.c". If all goes well the compiler will link with the
libraries and produce a test.ihx output file. If this step
fails (no test.ihx, and the linker generates warnings),
then the problem is most likely that sdcc cannot find the
/usr/local/share/sdcc/lib directory (see the Install trouble-shooting
section for suggestions).

The final test is to ensure sdcc can use the standard header
files and libraries. Edit test.c and change it to the following:

#include <string.h>
main() {
char str1[10];
    strcpy(str1, "testing");
}

Compile this by typing "sdcc test.c". This should generate
a test.ihx output file, and it should give no warnings such
as not finding the string.h file. If it cannot find the
string.h file, then the problem is that sdcc cannot find
the /usr/local/share/sdcc/include directory (see the Install
trouble-shooting section for suggestions).

 Install Trouble-shooting

 SDCC cannot find libraries or header files.

The default installation assumes the libraries and header
files are located at "/usr/local/share/sdcc/lib"
and "/usr/local/share/sdcc/include".
An alternative is to specify these locations as compiler
options like this: "sdcc -L /usr/local/sdcc/lib/small -I /usr/local/sdcc/include test.c".

 SDCC does not compile correctly.

A thing to try is starting from scratch by unpacking the
.tgz source package again in an empty directory. Confure
it again and build like:

make 2&>1 | tee make.log

After this you can review the make.log file to locate the
problem. Or a relevant part of this be attached to an email
that could be helpful when requesting help from the mailing
list.

 What the "./configure"
  does

The "./configure" command is a script
that analyzes your system and performs some configuration
to ensure the source package compiles on your system. It
will take a few minutes to run, and will compile a few tests
to determine what compiler features are installed.

 What the "make" does.

This runs the GNU make tool, which automatically compiles
all the source packages into the final installed binary
executables.

 What the "make install"
  command does.

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.

 Additional Information for Windows Users

<pending: is this up to date?>

The standard method of installing on a Unix system involves
compiling the source package. This is easily done under
Unix, but under Windows it can be a more difficult process.
The Cygwin is a large package to download, and the compilation
runs considerably slower under Windows due to the overhead
of the Cygwin tool set. An alternative is to install a pre-compiled
Windows binary package. There are various trade-offs between
each of these methods. 

The Cygwin package allows a Windows user to run a Unix command
line interface (bash shell) and also implements a Unix like
file system on top of Windows. Included are many of the
famous GNU software development tools which can augment
the SDCC compiler.This is great if you have some experience
with Unix command line tools and file system conventions,
if not you may find it easier to start by installing a binary
Windows package. The binary packages work with the Windows
file system conventions.

 Getting started with Cygwin

SDCC is typically distributed as a tarred/gzipped file (.tgz).
This is a packed file similar to a .zip file. Cygwin includes
the tools you will need to unpack the SDCC distribution
(tar and gzip). To unpack it, simply follow the instructions
under the Linux/Unix install section. Before you do this
you need to learn how to start a cygwin shell and some of
the basic commands used to move files, change directory,
run commands and so on. The change directory command is
"cd", the move command is "mv".
To print the current working directory, type "pwd".
To make a directory, use "mkdir".

There are some basic differences between Unix and Windows
file systems you should understand. When you type in directory
paths, Unix and the Cygwin bash prompt uses forward slashes
'/' between directories while Windows traditionally uses
'\' backward slashes. So when you work at the Cygwin bash
prompt, you will need to use the forward '/' slashes. Unix
does not have a concept of drive letters, such as "c:",
instead all files systems attach and appear as directories.

 Running SDCC as Native Compiled Executables

If you use the pre-compiled binaries, the install directories
for the libraries and header files may need to be specified
on the sdcc command line like this: "sdcc -L c:\usr\local\sdcc\lib\small
-I c:\usr\local\sdcc\include test.c" if you are running outside
of a Unix bash shell.

If you have successfully installed and compiled SDCC with
the Cygwin package, it is possible to compile into native
.exe files by using the additional makefiles included for
this purpose. For example, with the Borland 32-bit compiler
you would run "make -f Makefile.bcc". A command line version
of the Borland 32-bit compiler can be downloaded from the
Inprise web site.

 SDCC on Other Platforms

 FreeBSD and other non-GNU Unixes - Make sure the GNU make
  is installed as the default make tool.

 SDCC has been ported to run under a variety of operating
  systems and processors. If you can run GNU GCC/make then
  chances are good SDCC can be compiled and run on your
  system.

 Advanced Install Options

The "configure" 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). 

bin/ - binary exectables (add to PATH environment variable)
bin/share/
bin/share/sdcc/include/ - include header files
bin/share/sdcc/lib/
bin/share/sdcc/lib/small/ - Object & library files for small
model library
bin/share/sdcc/lib/large/ - Object & library files for large
model library
bin/share/sdcc/lib/ds390/ - Object & library files forDS80C390
library

The command "./configure --prefix=/usr/local"
will configure the compiler to be installed in directory
/usr/local.

 Components of SDCC

SDCC is not just a compiler, but a collection of tools by
various developers. These include linkers, assemblers, simulators
and other components. Here is a summary of some of the components.
Note that the included simulator and assembler have separate
documentation which you can find in the source package in
their respective directories. As SDCC grows to include support
for other processors, other packages from various developers
are included and may have their own sets of documentation.

You might want to look at the files which are installed in
<installdir>. At the time of this writing, we find the following
programs:
 
In <installdir>/bin:

 sdcc - The compiler.

 sdcpp - The C preprocessor.

 asx8051 - The assembler for 8051 type processors.

 as-z80, as-gbz80 - The Z80 and GameBoy Z80 assemblers.

 aslink -The linker for 8051 type processors.

 link-z80, link-gbz80 - The Z80 and GameBoy Z80 linkers.

 s51 - The ucSim 8051 simulator.

 sdcdb - The source debugger.

 packihx - A tool to pack Intel hex files.

In <installdir>/share/sdcc/include

 the include files

In <installdir>/share/sdcc/lib

 the sources of the runtime library and the subdirs small
  large and ds390 with the precompiled relocatables.

In <installdir>/share/sdcc/doc

 the documentation

As development for other processors proceeds, this list will
expand to include executables to support processors like
AVR, PIC, etc.

 sdcc - The Compiler

This is the actual compiler, it in turn uses the c-preprocessor
and invokes the assembler and linkage editor.

 sdcpp (C-Preprocessor)

The preprocessor is a modified version of the GNU preprocessor.
The C preprocessor is used to pull in #include sources,
process #ifdef statements, #defines and so on.

 asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80
  (The Assemblers and Linkage Editors)

This is retargettable assembler & linkage editor, it was
developed by Alan Baldwin. John Hartman created the version
for 8051, and I (Sandeep) have made some enhancements and
bug fixes for it to work properly with the SDCC.

 s51 - Simulator

S51 is a freeware, opensource simulator developed by Daniel
Drotos ([mailto:[e-mail]]).
The simulator is built as part of the build process. For
more information visit Daniel's website at: [http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51] .

 sdcdb - Source Level Debugger

Sdcdb is the companion source level debugger. The current
version of the debugger uses Daniel's Simulator S51, but
can be easily changed to use other simulators.

 Using SDCC

 Compiling

 Single Source File Projects

For single source file 8051 projects the process is very
simple. Compile your programs with the following command
"sdcc sourcefile.c". This will compile, assemble and link
your source file. Output files are as follows

sourcefile.asm - Assembler source file created by the compiler
sourcefile.lst - Assembler listing file created by the Assembler
sourcefile.rst - Assembler listing file updated with linkedit
information, created by linkage editor
sourcefile.sym - symbol listing for the sourcefile, created
by the assembler
sourcefile.rel - Object file created by the assembler, input
to Linkage editor
sourcefile.map - The memory map for the load module, created
by the Linker
sourcefile.ihx - The load module in Intel hex format (you
can select the Motorola S19 format with --out-fmt-s19)
sourcefile.cdb - An optional file (with --debug) containing
debug information


 Projects with Multiple Source Files

SDCC can compile only ONE file at a time. Let us for example
assume that you have a project containing the following
files:

foo1.c (contains some functions)
foo2.c (contains some more functions)
foomain.c (contains more functions and the function main)

The first two files will need to be compiled separately with
the commands: 

sdcc -c foo1.c
sdcc -c foo2.c

Then compile the source file containing the main() function
and link the files together with the following command:


sdcc foomain.c foo1.rel foo2.rel

Alternatively, foomain.c can be separately compiled as well:


sdcc -c foomain.c
sdcc foomain.rel foo1.rel foo2.rel

The file containing the main() function must be the first
file specified in the command line, since the linkage editor
processes file in the order they are presented to it.

 Projects with Additional Libraries

Some reusable routines may be compiled into a library, see
the documentation for the assembler and linkage editor (which
are in <installdir>/share/sdcc/doc) for how to create a
.lib library file. Libraries created in this manner can
be included in the command line. Make sure you include the
-L <library-path> option to tell the linker where to look
for these files if they are not in the current directory.
Here is an example, assuming you have the source file foomain.c
and a library foolib.lib in the directory mylib (if that
is not the same as your current project):

sdcc foomain.c foolib.lib -L mylib

Note here that mylib must be an absolute path name.

The most efficient way to use libraries is to keep seperate
modules in seperate source files. The lib file now should
name all the modules.rel files. For an example see the standard
library file libsdcc.lib in the directory <installdir>/share/lib/small.

 Command Line Options

 Processor Selection Options

-mmcs51 Generate code for the MCS51 (8051) family of processors.
This is the default processor target.

-mds390 Generate code for the DS80C390 processor.

-mz80 Generate code for the Z80 family of processors.

-mgbz80 Generate code for the GameBoy Z80 processor.

-mavr Generate code for the Atmel AVR processor(In development,
not complete).

-mpic14 Generate code for the PIC 14-bit processors(In development,
not complete).

-mtlcs900h Generate code for the Toshiba TLCS-900H processor(In
development, not complete).

 Preprocessor Options

-I<path> The additional location where the pre processor
will look for <..h> or "..h"
files.

-D<macro[=value]> Command line definition of macros. Passed
to the pre processor.

-M Tell the preprocessor to output a rule suitable for make
describing the dependencies of each object file. For each
source file, the preprocessor outputs one make-rule whose