title artwork

ARM7 Tools Installation

    My one page long, ugly but 100% accurate, setup tutorial for Mac OSX!

step 1 : download devkitARM_r11_OSX.tar.bz2 from sourceforge

step 2 : expand it into files using any GUI based tool (stuffit)

step 3 : use the finder to rename devkitARM_r11_OSX folder into simply "devkitARM"

step 4 : reveal hidden directory to copy the "devkitARM" directory using menu command in the finder called "Go To Folder..." in the Go menu or else use
Command-SHIFT-G in the Finder. In the dialog that opens up enter '/usr/local' (excluding parens) and hit return

step 5 : in the new window that opened up showing contenets of "/usr/local", drag "devkitARM" into it while holding option key, to make a copy.


We are done adding devkitARM we need to add it to paths.

To set the path to the bin tools of the freshly installed toolchain we need to enter it in a command line tool.

step 6 :
launch the free apple application called 'terminal" located in "/Applications/Utilities"

step 7 : copy and paste the single command :
export PATH=$PATH:/usr/local/devkitARM/bin

This allows the commands such as "arm-elf-cpp", "arm-elf-as" and "arm-elf-objcopy" to be located.
(I could have provided a downloadable Applescript file you could have executed but this is simple enough to copy and paste)

Now we need to install libgba source files and compile it into a library
step 8 : download libgba-0.1.0.tar.gz from sourceforge
step 9 : expand it into a folder of files using any GUI based tool (stuffit) it creates a folder called "libgba-0.1.0"

step 10 : go back and use the Terminal application (the window should be already open), type the command "cd" collowed by a space and do not hit return yet

step 11 : We now want to drag-copy the finder created path to the folder called "libgba-0.1.0" into the terminal window and Apple will append the full path at the flashing cursor.
To do this open up the window in the finder called "libgba-0.1.0" and then in the titlebar , press and hold the mouse down while clicking into the tiny folder icon left of the the title "libgba-0.1.0" to start dragging.
(In this step the keyboard is left alone, though you may need to tap "control key" first and release it to get the shorcut trick to work in some versions fo the Finder.)

step 12 : continue dragging this floating item into the openned Terminal application and let go in the Terminal window

The path will be drawn after the "cd " , awaiting you to merely hit return.
Here is the full command as shown on my machine (different than yours, certainly)

"cd /\342\200\242\342\200\242\ downloads/\342\200\242\ GameBoy\ Advance\ development/libgba\ -\ VITAL/libgba-0.1.0"

step 13 : Now switch the focus to the terminal application, instead of the finder, by clicking on the terminal window. This allows the keyboard to send commands.

step 15 : Simply hit return, the window should update showing you that you are in the new directory you selected.

step 16 : Type the "ls" command and hit return to list the contents and prove you are in the correct location.
the ls command should display a list of many files contained in "libgba-0.1.0" including a file called Makefile

MAKING the library

step 17 : if the path was set correctly in step "7" to the ARM compiler tools for gcc and the assembler, we can make the library now by enterring :

"make" in the terminal application. it should start compiling.
(I could have provided a downloadable Applescript file you could have executed but this word (make) is simple enough to copy and paste or type)

the make file tries to compile the source and will emit the command "arm-agb-elf-gcc -O2 -I. -marm -o marm/libgba.o -c libgba.c"

If you see the error message in the terminal app of "make: arm-agb-elf-gcc: Command not found" then the path does not have a path to the compiler tool called "arm-agb-elf-gcc"
This is normal, unless you installed a larger slower set of OSX arm compilation tools previously at an earlier time.
If so you need to modify the makefile to use the correct name in the path to the bins.
To see a list of the compiler tools we use from devkitARM use the "ls" command in the correct location as follows :

step 19 : paste the following "ls" command into terminal app window and hit return:
"ls /usr/local/devkitARM/bin"

it should display :
alignbin arm-elf-c++ arm-elf-gcc arm-elf-ld arm-elf-ranlib arm-elf-strip
arm-elf-addr2line arm-elf-c++filt arm-elf-gcc-3.4.3 arm-elf-nm arm-elf-readelf
arm-elf-ar arm-elf-cpp arm-elf-gccbug arm-elf-objcopy arm-elf-size
arm-elf-as arm-elf-g++ arm-elf-gcov arm-elf-objdump arm-elf-strings

As you can see, the compiler is NOT called arm-agb-elf-gcc, it is called simply arm-elf-gcc, and requires us to change the Makefile used to compile libgba.c

step 20 : select a text editor to edit the file Makefile. Editing a makefile is risky if you accidentally convert tabs to spaces or damage a tab by adding a space. There are commands that are preceded by tabs in a Makefile that must not be damaged.
step 21 : use the selected text editor and look for the section showing the two lines :

AR = arm-agb-elf-ar
CC = arm-agb-elf-gcc

notice it refers to tools that we do not desire to install.

We need to search and replace the prefix "arm-agb-elf" used throughout the makefile and substitute it with "arm-elf"
This will affect the follwing two lines as well during the search and replace :

INSTALL = /usr/local/devkitadv/arm-agb-elf/lib/
INSTALLH = /usr/local/devkitadv/arm-agb-elf/include

perform the search and replace

step 22 :
We need to search and replace the toolchain string "devkitadv" used within makefile and substitute it with our desired newer better toolchain called "devkitARM" that we installed in step 5.

So replace devkitadv in the makefile with devkitARM wherever it is found.

step 23 :
save the file and close it.

step 24 :
We can make the library now by enterring :

"make" in the terminal application. It should start compiling.

If it fails again with the message "make: arm-agb-elf-gcc: Command not found" then perhaps this window session merely needs the path enterred again (it is not persistant across shell launches). Enter it

export PATH=$PATH:/usr/local/devkitARM/bin


you should see a variety of messages in the terminal including :

arm-elf-ar rcs marm/libgba.a marm/libgba.o marm/gbavid.o marm/gbadma.o marm/gbabkg.o marm/gbasfx.o marm/gbajoy.o marm/gbatim.o marm/gbairq.o marm/gbaobj.o

the last line might display the error "rm: -f: No such file or directory" but this is OK.

At this point, four different libraries were created in the four folders called :

libgba.o and libgbax.o libraries are the two we care about most. "thumb" is 16 bit special compact opcode mode of the ARM7.


At this point we can use Apples Xcode tool to create projects. (freely downloadable or found on the 4th CD in the 4 cd set of OS installer discs).


example code :

a set of four ARM7 gameboy advance simple code examples that use the library we just compiled can be downloaded by entering the follwoing two commands
after first creating a directory and then using the "cd" command to enter the location to ldownload these directories.

cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/devkitpro login
cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/devkitpro co -P examples/gba

The four projects are directories labelled :

Those Gameboy Advance ARM examples are too complex for your first "hello world" project.

Instead we will create a "hello world" from scratch follwoing these next steps...

step 1 : obtain and install Xcode if needed :

step 2 : launch Xcode

step 3 : create a directory somewhere on your hard drive to hold our new project (preferably in your home directory, perhaps within a new directory called "sourcecode" if desired)

step 4 : choose File > New Project

a window opens listing projects. select EMPTY PROJECT and click the "Next" button.

, and give it a name and store it in the directory we created

step 5 : Create a new external target by choosing Project > New Target, and choosing External from the list of "special targets". YOu are presented with a Target Name with a default of "Untitled" highlighted. Alter it to "standard" or some other word.

step 6 : using xCode menu command File > New File create a new empty text file we will store main.c into. Select choice "Empty File in Project" and select "Next"

step 7 : A dialog is shown with the path and filename default "untitled" highlighted. Change "untitled" into "main.c" and press Finish button. A blank document will open.

step 8 : In the blank document past the following complete minimal rom program (excluding ==='s) :

#define k_VIDEO_WIDTH (240)

/* For compilation tools */
int __gba_multiboot;

unsigned short* video_ram= ((unsigned short int*)0x06000000);

int main(void)
    *(unsigned long int*)0x04000000= 0x0403;
    /* Draw three tiny colored pixels using 16 bit colors 5:5:5 */
    video_ram[120 + 80*k_VIDEO_WIDTH]= 0x001f;
    video_ram[136 + 80*k_VIDEO_WIDTH]= 0x03e0;
    video_ram[120 + 96*k_VIDEO_WIDTH]= 0x7c00;

    /* delay in infinite loop. */

step 9: , save and close the main.c file

step 6 : using xCode menu command File > New File create a new empty text file we will store makefile.mak into. Select choice "Empty File in Project" and select "Next"

step 7 : A dialog is shown with the path and filename default "untitled" highlighted. Change "untitled" into "makefile.mak" and press Finish button. A blank document will open.

step 8 : In the blank makefile document past the following complete minimal rom makefile (excluding ==='s) :

# makefile.mak
# Note : A very minimal makefile (examine other makefile examples for non-trivial projects)
# WARNING : Ensire tab before each command, not a space

PROJ= helloworld
CC= arm-elf-gcc
OBJCOPY= arm-elf-objcopy

# path to tools examples - this can be deleted if set in shell (disabled)
#export PATH    :=    /usr/local/devkitARM/arm-elf/bin:/bin
#export PATH=$PATH:/usr/local/devkitARM/bin

ARMLIBS = /usr/local/devkitARM/arm-elf/lib/
ARMH = /usr/local/devkitARM/arm-elf/include/

# the PHONY command allows user to accidentally store a file named "build" in the directory
.PHONY : build
build :
    $(CC) -mthumb-interwork -c main.c
    $(CC) -specs=$(ARMLIBS)gba_mb.specs -mthumb-interwork main.o -o $(PROJ).elf
    $(OBJCOPY) -v -O binary $(PROJ).elf $(PROJ).gba
#    The following PC windows tool is not needed if only using OSX emulator to run the rom
#    gbafix $(PROJ).gba

.PHONY : clean
clean :
    @rm -fv main.o
    @rm -fv $(PROJ).gba
    @rm -fv $(PROJ).elf


step 10: Save and close the makefile.mak file into a new directory called sources

step 11: Add our main.c source code file and makefile.mak into the project. Control-click on the project root in the Xcode project tree and select Add > Exising Files...
Navigate one level down into the project folder, to reveal the main.c or makefile.mak
Double Click on the main.c file or makefile.mak
Press the Finish button
repeat for the other file(s)
If any files are listed duplicated in the upper left of the project, the duplicate references can be deleted by highlighting and hitting the "DEL" key or the Dlete command in the Edit menu.

step 12: Double Click on targe in target menu with the name we selected for the standard target ("labelled standard")

step 13: At this point a large dialog box window opens up for the build options. We are gling to alter the Arguments section.
Change "$(ACTION)" to read "--makefile=sources/makefile.mak $(ACTION)" instead, so that we can use a makefile that has a filename suffix, as legal files should use on windows and mac osx.

step 14: Close the large dialog box window using the only obvious way possible using the red control in the upper left of the window. There is no "OK" or "Finish" button in XCode yet.

step 15 : Using the Build Menu, Select the detaild build window "Show Detailed Build Results" (Command-SHIFT-B)

step 16 : Clean out junk files using the CLEAN broom icon.

step 17 : Build It! Merely click on the Build icon. It should build fine with no errors.


How to run the rom file in an OSX based Gameboy Advanced emulator.

If you have "Boycott Advance - 0.3.5" or "Visual Boy Advance" installed fully on the Mac merely double clicking the gba file (helloworld.gba) should launch and run the rom.

There is a second library of proprietary object code that can optionally be installed for "Boycott Advance" called "emulator enhancer 1.5.4.
This optional library is a folder that is dropped into the user library area called /Library/Application/Support/
This optional library allows a few large screen video drawing modes and game controller USB code.

The GBA OSX emulator can be located using huge database of mac emulators at http://www.emulation.net


Thats it. (For simple installation) next up... Assembly language development aid

Beware capitalization sensitivity if importing source code files used on other platforms. The mac tools
are defective because they are sensitive to Case, and also sometimes sensitive to space characters.


  Refer to Assembly language tutorial next, and soon to be online, single interrupt and multiple pending interrupt scheduling


Home page (return to ARM page)

Email server admin at: webmaster4@NiftySpot.com