Compiling Libdragon Projects

Home » N64 Homebrew » Libdragon Tutorial » Compiling Libdragon Projects

Compiling (or building) is the process of taking your source code and converting it to a runnable binary file. There are a few intermediate steps like preprocessing and linking, but to keep it simple we’ll refer to the whole thing as “Compiling”. In this page we’ll go through how to start compiling Libdragon projects.

This guide assumes that you have gone through the steps in the Setting up Lib

Preparing Docker

The first step is to get your docker engine running. You can do this by opening Docker Desktop. If you don’t have docker open, or you didn’t create a Libdragon Container, you might get an error like this when running Make:

Running the compilation command

The compilation command is fairly simple. Simply open your terminal/CMD and move to the correct directory and run this command:

libdragon make

That will take all your source code and produce a bunch of output files including your Nintendo 64 ROM.

If you get an error that says *** No rule to make target '/include/n64.mk'. Stop. it means that you’re using a regular make instead of libdragon make.

Output files explained

Once the project has been compiled, you’ll get a bunch of new files in your project folder.

The main file you’ll be interested in is the hello.z64 file, which is going to be your N64 ROM file. You can chuck this into your favourite emulator and run it to see how your program works.

The rest of the file are put into the ./build/ directory. Assuming you’re working with the skeleton project, they are as follows (it will be different for more complex projects):

• hello.elf – This is the Executable Linkable Format file. It is a binary file that has object code, shared libraries and executable code.
• hello.elf.bin & hello.elf.sym – Not sure what these are, but they look like they are files that accompany the main .elf file that contain binary machine code and symbol information.
• hello.map – A text file that contains information about how memory is laid out and the various data/code sections of the executable.
• main.d – Dependency file. It shows what files the build is dependent on. In this simple program it will only mention main.o which is built from main.c.
• main.o – The object file for main.c. This contains the compiled code used the is outputted in the compiling stage of the build (before linking)

Note that the files called “hello._” are related to the build as a whole, while the ones that are called “main._” are referring to the individual source files.

If you’re using Git for version tracking, it might be wise to add these file to your .gitignore exclusion list since they will be changing often, take up space and are not very relevant to the development of your project. They can be useful for debugging if you know how to do that. Just add this:

build/
*.z64

Running the ROM

Run the ROM in an emulator of your choice. I tend to use Project 64, but for this case I’ll use Ares. You should get something like this:

There you go, your first Libdragon N64 ROM!