Contents of the "nes.lib" in CC65

I've got a question about the file "nes.lib" of CC65:

Is this file just there for implementing the pure language features of C, like being able to pass parameters to functions etc., or does it also include help functions that I can actually call in my code?

For example, there is an "nes.h" (which is curiously not in the "cc65-nes-2.13.3-1.zip", but in the general "cc65-win32-2.13.3-1.zip") with two functions: waitvblank and get_tv.

Are these two functions implemented in "nes.lib"?
And are there other functions that have an implementation in "nes.lib" that I could use when including a certain header file?

Or is the "nes.lib" really just there for converting C language constructs into Assembler?

The nes.lib that you can get with CC65 is not very useful, I don't recommend it.

Shiru made a version of it that he distributed with his NES C tutorial. It is better.

You can use "ar65 l nes.lib" so see the object files contained in the library, in this library there will be one function contained in each object file, but that's just because of the convention. I'm not sure how to look at the exported symbols in an object file or library from cc65 (does anyone know?).

Basically, the nes.lib should contain the necessary C runtime implementation to support the C compiler, plus some NES specific startup stuff, plus whatever useful NES specific functions shiru or whomever wanted to put inside there.

In my own stuff, I use a CRT library built from the stuff in libsrc/runtime/ (minus condes.s, stkchk.s, callirq.s, and callmain.s) plus libsrc/common/copydata.s from the CC65 libraries, and then I wrote my own custom NES startup stuff which also went in there. I used it to make a music ROM for John Coltrane's giant steps. Source here: http://rainwarrior.ca/music/coltrane_src.zip

The thing is: When I write an NES game in C, I want to do everything myself and not use any external functions.

So, if this is part of my code:

and the compiler needs a lib for it because passing parameters, creating local variables or handling two byte values is internally done with function calls in Assembler, then I will of course include that lib.

But what I don't want to have is this here:

Using a lib that the compiler needs for even converting the C language syntax into Assembler, that's of course necessary. But using a lib for some helper functions that encapsulate the behavior of the NES and that I can call in my code, that's not what I want because I want to write those things all by myself.

So, when I link the "nes.lib", what will end up in my NES file?

Will the dozens of functions that are included in the "nes.lib" be included in the final ROM? Or are only functions that are actually used somewhere in the code linked in the end?

What happens if I or the compiler that converts my C files to ASM files uses the "import" command to make a function from the lib known to my code, but that function is never actually used? Will that function be included in the NES file?

Only the functions that you use will be included in the final ROM. Actually technically cc65 only does this at module (source code file) level, but the platform libraries like nes.lib have every function in a separate file so it works as you'd expect.


This is only a guess, but I'd guess an .import statement is enough for the function/module to be included into the build. (Reasoning: sometimes it would make sense to ensure a certain module is imported, without using anything from that module)

The C compiler will never generate .import statements unless you use "extern", or it needs one of the compiler support functions (for things such as parameter passing/retrieval, multiplication, etc).

The nes.lib that I compiled does not have any of my code, only the C compiler runtime. There are things like math routines, popa, popax etc. Here is all what the nes.lib contains.

Right, I remembered it incorrectly. It wasn't the functions that are imported.

But the compiler does always import this:
What are those variables good for?

Besides, how does the compiler use calls like this one:
(this is generated when a function in C has parameters)
without including something like this in the assembler source file:



But in this case, what's the reason behind creating such a lib in the first place instead of using the one from the CC65 website?

Offhand I can say "sp" is a pointer to the cc65's software stack and tmp1, ptr1 and ptr2 are obviously some temporary helper variables. Information about others you can find out by googling "<variable name> cc65".

It is not creating, it is just compiling existing sources. The reason is to know what is inside rather than use a black box and to exclude all unwanted stuff (lib size is reduced well). I would put my code there too, but I prefer to have it in source form in case of customization for a project (happens often).

Yeah, that makes sense.

I'm asking myself why those generic C runtime functions are implemented in a lib that's specifically for the NES anyway. I would understand it if the "nes.lib" includes actual callable functions like the stuff from the conio. But does the conversion from pure C syntax into Assembler really work differently on different platforms? Doesproduce different Assembler code for the NES and for the C64?

For the most part, no, there is not much that is NES specific in the nes.lib that you can get with CC65. The common CRT is the bulk of it. There is some NES specific stuff, but the kind of stuff they have in CC65's nes.lib is kinda garbage for game making purposes. It's purpose is to help port CC65 programs from other platforms to NES, and they're not designed around game making at all, really.

That's why you should use shiru's cut down nes.lib, or build your own like what I suggested (basically what's in the runtime folder with a few additions/removals). The set I used for my coltrane.nes project is basically the bare minimum needed to support CC65's C compiler, and all the NES specific stuff is in other assembly files I wrote for that project.

Here's the list of what I put in my CRT library:



See the crt0.s in my project for additional startup code needed to initialize the CC65 C runtime (it is very minimal, just need to setup the stack pointer and call the copydata routine from common). The other thing you need is a linker configuration that has the segments required by the C runtime, of which you can look at my nrom.cfg for an example.

Well, that's just a misleading file name. This part of code is normally called 'runtime.lib' (the source folder is called like this), so I probably should rename it after removing the unneeded NES-related stuff.

Edit: well, in fact, I did rename the lib into runtime.lib. The original nes.lib (602K) from CC65 was provided with Alter Ego and Zooming Secretary, but in the C examples and Chase it is runtime.lib (104K). Completely forgot about it.

Yeah, if I ever create a complete game, I might actually remove the linkage to the "nes.lib" and manually insert all the function the compiler complains about into a separate file. Until then, for simplicity's sake, I will just leave it as it is.

Thanks for all the information.

This increases maintenance cost and could easily make the code not compile and link on a different version of ca65, or compile and link but crash, due to the versions of the runtime routines differing.

So, you suggest me not to use an external runtime library and stick with the official one, correct?

My advice is to list the benefits of using Shiru's, or your plucked functions, and weigh them against the costs and choose based on which is more beneficial. Does the standard one impose anything on the generated ROM over a custom one if you don't explicitly call anything from it? (e.g. does it have some constructor code that you can't eliminate?)

Questions like that were the reason I was asking in the first place.

So, does it?