{"id":62,"date":"2023-05-05T14:33:00","date_gmt":"2023-05-05T13:33:00","guid":{"rendered":"https:\/\/techblog.dansbo.dk\/?p=62"},"modified":"2024-01-04T14:57:56","modified_gmt":"2024-01-04T13:57:56","slug":"how-to-make-library-modules-for-cc65-ca65","status":"publish","type":"post","link":"https:\/\/techblog.dansbo.dk\/?p=62","title":{"rendered":"How to make library modules for CC65\/CA65"},"content":{"rendered":"\n

The text below is copied directly from the posts at\u00a0https:\/\/<\/a>www.commanderx16.com<\/a>\/forum\/viewtopic.php?p=25298<\/a>. All credits should go to the respective authors, ZeroByte and Kliepatsch.<\/em><\/p>\n\n\n\n

Making libraries in CA65 is quite straightforward, but your code needs to be configured properly for use in \u201cmulti-file\u201d projects.<\/p>\n\n\n\n

TL;DR:<\/strong><\/p>\n\n\n\n

Below you will find a simple set of example code and build instructions if you want to \u201cjust do it\u201d without any further explanations.<\/p>\n\n\n\n

The basics:<\/strong><\/p>\n\n\n\n

Creating a library is essentially just packaging up .o files into a library file. Therefore, your library routines should be written so that they would work as independent source files in any other multi-source-file project. For this howto, let\u2019s suppose you want to create a library routine \u201chelloworld\u201d which just uses CHROUT to print \u201chello world.\u201d First, let\u2019s consider how you would use this routine if it were written in a stand-alone source file.<\/p>\n\n\n\n

First, you would create a file \u201chello.asm\u201d which defines the routine and imports\/exports the necessary symbols to perform its task and be reachable from the rest of the project. (more on symbol export\/import later). With your routine in its own file, you build your project by listing all source files on the command line:<\/p>\n\n\n\n

cl65 -t cx16 -o MYPROG.PRG myprog.asm hello.asm<\/code><\/pre>\n\n\n\n
Assuming that these assembly files know how to properly import and export the required symbols, this command will build MYPROG.PRG which can now be run. Ostensibly, somewhere in main.asm, there is a call to \u201chelloworld\u201d which prints that string to the screen. This command works pretty much the same for C projects:<\/p>\n\n\n\n
cl65 -t cx16 -o MYPROG.PRG main.c hello.c<\/code><\/pre>\n\n\n\n
Of course, you can mix and match \u2013 main.c can use assembly code from assembly sources, e.g: (all-in-one method)<\/p>\n\n\n\n
cl65 -t cx16 -o MYPROG.PRG myprog.c hello.asm<\/code><\/pre>\n\n\n\n
Keep in mind that cl65 is sort of a front-end batch processor command that performs several sub-steps in order to assemble and link your program.<\/p>\n\n\n\n
Step-by-step building:<\/strong><\/p>\n\n\n\n
The reason you can easily mix C and assembly is that behind the scenes, cl65 first compiles\/assembles each source file into an object file (.o) An object file is as close as the compiler or assembler can get to the final binary machine code of your program. The one thing that\u2019s missing during this step is the final resolution of symbols into the actual memory addresses based on where the program is set up to be loaded in memory. If \u201chelloworld\u201d is built at the beginning of your program, it will be in a different location in memory than it would if it were appended to the end of your program. Thus, it\u2019s not known just yet exactly what address to use for any JSR \/ JMP statements calling your code. Thus the symbol \u201chelloworld:\u201d remains unresolved.<\/p>\n\n\n\n
The final step of resolving these symbols is done by the linker (ld65). It puts all of the pieces of object code together into the final program. Since the linker is what decides the final locations where everything is actually going to go, it has enough information to turn these remaining unresolved symbols into their final actual memory addresses. It does this, combines all of the object code together, and writes out the .PRG file which can now be loaded into memory and run on the X16.<\/p>\n\n\n\n
Before, we performed all of these steps at once. However, you can tell cl65 to skip the linking phase on your project and do only the compiling\/assembling. You do this by adding the -c command-line switch. This will cause cl65 to stop short of calling the linker to create a complete executable program. Instead, it will simply create the object files from your sources.<\/p>\n\n\n\n
cl65 -t cx16 -c myprog.c\n\ncl65 -t cx16 -c hello.asm<\/code><\/pre>\n\n\n\n
Running these two commands produces the files main.o and hello.o \u2013 note that you need to run them as separate commands \u2013 once for each source file.<\/p>\n\n\n\n
You can then finish your build just as if these files were the source files: (precompiled method)<\/p>\n\n\n\n
cl65 -t cx16 -o MYPROG.PRG myprog.o hello.o<\/code><\/pre>\n\n\n\n
Running these two commands produces the files main.o and hello.o \u2013 note that you need to run them as separate commands \u2013 once for each source file.<\/p>\n\n\n\n
You can then finish your build just as if these files were the source files: (precompiled method)<\/p>\n\n\n\n
cl65 -t cx16 -o MYPROG.PRG myprog.o hello.o<\/code><\/pre>\n\n\n\n
You could even pre-assemble the helloworld module, but compile directly from source on the main .c file: (hybrid method)<\/p>\n\n\n\n
cl65 -t cx16 -c hello.asm\n\ncl65 -t cx16 -o MYPROG.PRG myprog.c hello.o<\/code><\/pre>\n\n\n\n
All of these methods will produce the same executable program MYPROG.PRG \u2013 the second and third methods just take multiple steps. These \u201cgranular\u201d methods are useful in larger projects. If you compile your sources into object code, then you don\u2019t need to recompile everything whenever you only make changes to one source file. Suppose hello.asm did not change, but you made changes to myprog.c \u2013 you would recompile myprog.c as above in the (precompiled method), or using the hybrid method, but you would not need to reassemble hello.o as it has not changed. Make is designed to work with this mode of project building. Make will go through and determine which .o files are older than their source files, and only recompile those components.<\/p>\n\n\n\n
If your project had more auxilliary functions such as \u201cgoodbyeworld\u201d and \u201cwaitforkey\u201d in their own source files, you would pre-compile them and then add their filenames to the final build command:<\/p>\n\n\n\n
cl65 -t cx16 -o MYPROG.PRG myprog.c hello.o goodbye.o waitkey.o<\/code><\/pre>\n\n\n\n
Now we get to libraries:<\/strong><\/p>\n\n\n\n
A library file is simply an archive of .o files all packed together into a single file. Instead of having a bunch of .o files laying around in a directory, you simply have one library file, e.g. \u201cmytools.lib\u201d which includes routines like helloworld: from hello.asm, etc.<\/p>\n\n\n\n
So this means that to create it, all you need to do is first compile or assemble your sources into object files, and then add the object files to your library archive using the archive tool ar65.<\/p>\n\n\n\n
ar65 a mytools.lib hello.o goodbye.o waitkey.o<\/code><\/pre>\n\n\n\n
Note that these must be object files, not the uncompiled sources. Now, you no longer need to specify all of your individual source files:<\/p>\n\n\n\n
cl65 -t cx16 -o MYPROG.PRG myprog.c hello.o goodbye.o waitkey.o<\/code><\/pre>\n\n\n\n
Instead, you can just reference the library file:<\/p>\n\n\n\n
cl65 -t cx16 -o MYPROG.PRG myprog.c mytools.lib<\/p>\n\n\n\n
ld65 will go through the library archive when it needs to resolve symbols such as the names of your functions and variables defined in the archive.<\/p>\n\n\n\n
What about the symbols?<\/strong><\/p>\n\n\n\n
ld65 is able to find the symbols in the archive and use them for any code that needs them. However, the archive only contains the symbols that the sources told the compiler to export. Export means to make this symbol available from outside of this particular source file. If you do not export \u201chelloworld\u201d then that symbol can\u2019t be called from myprog.prg.<\/p>\n\n\n\n
C vs Assembly symbols: The cc65\/ca65 suite uses the convention that any symbols in C will be presented to assembly with an underscore _ prepended to them. Thus a variable \u201cfoo\u201d in C would be seen as the symbol \u201c_foo\u201d in assembly. Likewise, any symbols with leading underscores in assembly will be presented in C with the leading underscore removed.<\/p>\n\n\n\n
Thus, your helloworld function could also have another symbol: \u201c_helloworld\u201d which points to the same code. Doing this, you may now call \u201chelloworld()\u201d from C just as you would from assembly.<\/p>\n\n\n\n
In myprog.c, you would declare it as follows:<\/p>\n\n\n\n
extern void helloworld();\n<\/code><\/pre>\n\n\n\n
That\u2019s all you need to do to access a simple function like helloworld: that was actually written in assembly.<\/p>\n\n\n\n
Had helloworld been written in C, then you could still access it from assembly projects:<\/p>\n\n\n\n
.import _helloworld\n\n...\n\njsr _helloworld<\/code><\/pre>\n\n\n\n
If you would like to be able to refer to the same function as helloworld: in assembly and as helloworld() in C, you can simply create a second symbol using the := syntax in your assembly module, and export both symbols:<\/p>\n\n\n\n
.export _helloworld\n.export helloworld\n\n_helloworld := helloworld\n\n.proc helloworld: near\n  ;code\n.endproc<\/code><\/pre>\n\n\n\n
Variables:<\/strong><\/p>\n\n\n\n
Lastly, I should point out that importing and exporting variables works in exactly the same way. Just remember that \u201cvariables\u201d and \u201ctypes\u201d don\u2019t exist in assembly, at least not in the sense that they do in C. In assembly, everything is just a reference to an address. So if you reserve some space and give it a symbol name in assembly, and export that symbol, this is enough to pass it between C and assembly. (the _ rules still apply, obviously)<\/p>\n\n\n\n
.export foo\n.export _foo\n\n.segment \"BSS\"\n\nfoo:  .res 2 ; reserve 2 bytes of memory for a 16-bit value, foo\n_foo := foo ; alias it as _foo for importing into C projects<\/code><\/pre>\n\n\n\n
In case you\u2019re wondering, BSS segment is for uninitialized variables. I.e.: no values are emitted into the binary created by the build process. It is expected that programs will write values into this memory during run time. Basically, it just reserves memory space without adding size to the actual code. Other segments where you might put data:<\/p>\n\n\n\n
RODATA\u00a0:\u00a0for constants such as strings, lookup tables, etc.<\/p>\n\n\n\n
.segment \"RODATA\"\nmessage: .asciiz \"hello world\"<\/code><\/pre>\n\n\n\n
DATA : for initialized variables:<\/p>\n\n\n\n
.segment \"DATA\"\nbar:  .word  $1000<\/code><\/pre>\n\n\n\n
Any concept of type is defined in C, as assembly just doesn\u2019t care. In C, you would define foo: \u201cextern uint16_t foo;\u201d or if it\u2019s a pointer of some sort, it could be \u201cextern char* foo;\u201d etc.<\/p>\n\n\n\n
Nutshell:<\/strong><\/p>\n\n\n\n
    \n
  1. Create the sources for your library just as any other components of a project<\/li>\n\n\n\n
  2. Compile\/assemble them as object files\n