bslathi19/cc65
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Fixed documentation about search paths, especially search paths for configs.

Browse Source 
Updated the intro a bit.


git-svn-id: svn://svn.cc65.org/cc65/trunk@4204 b7a2c559-68d2-44c3-8de9-860c34a00d81
This commit is contained in:
uz
2009-09-20 18:06:29 +00:00
parent 35646b6499
commit b1f4526e52
2 changed files with 37 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
doc/intro.sgml
View File

@@ -25,13 +25,19 @@ one assembly modules. This file does <em/not/ contain a complete reference for
the tools used in the process. There are separate files describing those tools, the tools used in the process. There are separate files describing those tools,
in detail (see <url url="index.html">). in detail (see <url url="index.html">).
You are assumed to have downloaded and extracted the executables and the I do assume that you have downloaded and installed the compiler and
target-specific files. For example: for Windows users targeting C64, you need target-specific files. Windows users should use the friendly .exe installer
<bf/cc65-win32-2.10.1.zip/ and <bf/cc65-c64-2.10.1.zip/ (or, whatever the (named cc65-2.13.0-1.exe for version 2.13.0 of the package - adjust the
current cc65 version is) extracted to the same directory. If you received the version number if necessary). It does not only install the target files, but
files as a bzip2 archive (extension <bf/.bz2/), you will need to get <url will also set up necessary environment variables for you.
url="http://sources.redhat.com/bzip2/#bzip2-latest" name="the bzip2 package">
to decompress it. If you're going for the .ZIP archives, please note that there is one file for
the host platform (Windows, DOS or OS/2), one file for each target platform
(C64 or whatever) and a separate file containing the docs (which include the
file you're currently reading). So for most uses, you will need at least 3
files and unpack all three into one directory. In case of the .ZIP archives,
you will also need to set the environment variables <tt/CC65_INC/,
<tt/LD65_LIB/ and <tt/LD65_CFG/ as described below.
<bf/Note/: There is a much simpler way to compile this example, by using the <bf/Note/: There is a much simpler way to compile this example, by using the
<bf/cl65/ compile-and-link utility. However, it makes sense to understand how <bf/cl65/ compile-and-link utility. However, it makes sense to understand how
@@ -42,9 +48,11 @@ described <ref id="using-cl65" name="later">.
<sect1>Before we start<p> <sect1>Before we start<p>
You will find a copy of the sample modules, used in the next section, in the You will find a copy of the sample modules, used in the next section, in the
"<tt>cc65/samples/tutorial</tt>" directory. Please make sure that the compiler "<tt>cc65/samples/tutorial</tt>" directory. If you encounter problems with
and linker can find the include and library files, by setting the environment missing include files and/or libraries, please check the environment variables
variables <tt/CC65_INC/ and <tt/CC65_LIB/, respectively. <tt/CC65_INC/, <tt/LD65_LIB/ and <tt/LD65_CFG/. They should point to the
<tt/include/, <tt/lib/ and <tt/cfg/ subdirectories of the directory, where you
installed cc65.
<sect1>The sample modules<p> <sect1>The sample modules<p>
@@ -102,7 +110,8 @@ is the C64.
</verb></tscreen> </verb></tscreen>
<tt/c64.o/ (the startup code) and <tt/c64.lib/ (the C64 version of the runtime <tt/c64.o/ (the startup code) and <tt/c64.lib/ (the C64 version of the runtime
and C library) are provided in binary form in the cc65 package. and C library) are provided in binary form in the cc65 package. Actually, the
startup code is contained in the library, so you won't need to care about it.
@@ -116,7 +125,7 @@ In the example above, we would use the following command line, to translate
<tt/hello.c/ into <tt/hello.s/: <tt/hello.c/ into <tt/hello.s/:
<tscreen><verb> <tscreen><verb>
cc65 -O -I ../../include -t c64 hello.c cc65 -O -t c64 hello.c
</verb></tscreen> </verb></tscreen>
The <tt/-O/ switch tells the compiler to do an additional optimizer run, which The <tt/-O/ switch tells the compiler to do an additional optimizer run, which
@@ -124,9 +133,6 @@ is usually a good idea, since it makes the code smaller. If you don't care
about the size, but want to have slightly faster code, use <tt/-Oi/ to inline about the size, but want to have slightly faster code, use <tt/-Oi/ to inline
some runtime functions. some runtime functions.
The <tt/-I/ switch gives a search path for the include files. You may also set
the environment variable <tt/CC65_INC/ to the search path.
The <tt/-t/ switch is followed by the target system name. The <tt/-t/ switch is followed by the target system name.
If the compiler does not complain about errors in our "hello world" program, we If the compiler does not complain about errors in our "hello world" program, we
@@ -176,22 +182,16 @@ C library, are in an object-file archive named after the system, in this case,
"<tt/c64.lib/". We have to specify that file on the command line, so that the "<tt/c64.lib/". We have to specify that file on the command line, so that the
linker can resolve those functions. linker can resolve those functions.
A second file (this time, an object file) needed is the startup code that
prepares the grounds for the C program to run. The startup file must be
executed first, so it must be the first file on the linker command line.
Let's link our files to get the final executable: Let's link our files to get the final executable:
<tscreen><verb> <tscreen><verb>
ld65 -t c64 -o hello c64.o hello.o text.o c64.lib ld65 -t c64 -o hello hello.o text.o c64.lib
</verb></tscreen> </verb></tscreen>
The argument after <tt/-o/ specifies the name of the output file, the argument The argument after <tt/-o/ specifies the name of the output file, the argument
after <tt/-t/ gives the target system. As discussed, the startup file must be after <tt/-t/ gives the target system. The following arguments are object
the first input file on the command line (you may have to add a path here, if files or libraries. Since the target library resolves imports in <tt/hello.o/
<tt/c64.o/ is not in your current directory). Since the library resolves and <tt/text.o/, it must be specified <em/after/ those files.
imports in <tt/hello.o/ and <tt/text.o/, it must be specified <em/after/ those
files.
After a successful linker run, we have a file named "<tt/hello/", ready for After a successful linker run, we have a file named "<tt/hello/", ready for
our C64! our C64!
@@ -209,18 +209,11 @@ well-suited for our example.
To compile both files into one executable, enter: To compile both files into one executable, enter:
<tscreen><verb> <tscreen><verb>
cl65 -O -I ../../include -L ../../lib hello.c text.s cl65 -O hello.c text.s
</verb></tscreen> </verb></tscreen>
(The <tt/-I/ option is not needed if you are working under a Unix-like system
with the include files in their default path, or if the <tt/CC65_INC/
environment variable is set correctly. The <tt/-L/ option is not needed if the
libraries are in their default path, or if the <tt/CC65_LIB/ environment
variable is set correctly. &lsqb;Those two environment variables should be set to
absolute paths.&rsqb;)
The <bf/cl65/ utility knows how to translate C files into object files (it will The <bf/cl65/ utility knows how to translate C files into object files (it will
call the compiler, and then, the assembler). It does know also how to create call the compiler, and then the assembler). It does know also how to create
object files from assembly files (it will call only the assembler, for that). object files from assembly files (it will call only the assembler, for that).
It knows how to build an executable (it will pass all object files to the It knows how to build an executable (it will pass all object files to the
linker). And finally, it has the C64 as a default target, and will supply the linker). And finally, it has the C64 as a default target, and will supply the
@@ -239,12 +232,12 @@ url="cl65.html">.
<em/Note: this section is incomplete!/ <em/Note: this section is incomplete!/
Depending on the target, cc65 chooses several methods of making a Depending on the target, cc65 chooses several methods of making a program
program available for execution. Here, we list sample emulators and available for execution. Here, we list sample emulators and instructions for
instructions for running the program. Unless noted, similar instructions running the program. Unless noted, similar instructions would also apply to a
would also apply to a real machine. One word of advice: we suggest you clear real machine. One word of advice: we suggest you clear the screen at the
the screen at the start, and wait for a keypress at the end of your program, start, and wait for a keypress at the end of your program, as each target
as each target varies in it's start and exit conditions. varies in it's start and exit conditions.
<sect1>Apple <sect1>Apple

5
doc/ld65.sgml
View File

@@ -355,9 +355,12 @@ The config file search path contains in this order:
<enum> <enum>
<item>The current directory. <item>The current directory.
<item>A compiled in directory which is often <tt>/usr/lib/cc65/lib</tt> on <item>A compiled in directory which is often <tt>/usr/lib/cc65/cfg</tt> on
Linux systems. Linux systems.
<item>The value of the environment variable <tt/LD65_CFG/ if it is defined. <item>The value of the environment variable <tt/LD65_CFG/ if it is defined.
<item>The value of the environment variable <tt/CC65_LIB/ if it is defined.
Please note that use of this environment variable is obsolete and may
get removed in future versions.
<item>Any directory added with the <tt><ref id="option--cfg-path" <item>Any directory added with the <tt><ref id="option--cfg-path"
name="--cfg-path"></tt> option on the command line. name="--cfg-path"></tt> option on the command line.
</enum> </enum>