From WikiTemp, the GBAtemp wiki
(Windows)
 
(71 intermediate revisions by 15 users not shown)
Line 1: Line 1:
==3dsx homebrew==
+
{{3DSNav}}
===Development environment===
+
If you want to created homebrew in 3dsx format to be launched from Ninjhax exploit you will need to install DevkitPro with the 3DS User Library (CTRULib).
+
  
* Install DevkitPro + DevkitARM + CTRULib by following [http://sourceforge.net/projects/devkitpro/files/Automated%20Installer/ this guide] if you are using Linux or Mac.
+
This page contains general information for 3DS Homebrew developers.
* If you are using Windows, use the  [http://sourceforge.net/projects/devkitpro/files/Automated%20Installer/ automated-installer]. Install in C:\devkitPro\ and it will install all the latest versions of the required programs (you can disable DevKit PSP, but be sure to enable CTRULib in DevkitARM menu). It will create the environment variables automatically.
+
  
===Examples===
+
If you have any questions, you can come to GBAtemp's main [http://gbatemp.net/threads/homebrew-development.360646/ homebrew development and help thread]. It contains shared sources, examples and libraries.
You can find ctruLib homebrew examples here: https://github.com/smealum/ctrulib/tree/master/examples
+
  
To compile, open a command line window and browse to the homebrew folder and type make, or create a batch file in the same folder with the "make" command in it.
+
You can find all known resources (hardware registers, syscalls, utilities) to develop your homebrew on [http://3dbrew.org 3dbrew].
  
===Editor setup===
+
To develop 3DS homebrew you need a development environment consisting of tools, scripts and libraries which will be detailed below. The sources are compiled to binary using GNU GCC-ARM or devkitPro with devkitARM. The available tools and SDK work on Windows 32/64bit and Linux.
This section explains how to set up various editors to open and compile (existing) homebrew projects. If you want to start a new homebrew project, you should preferably copy an example project and edit the sources.
+
  
==== Programmers Notepad ====
+
The languages used to write homebrew are [[wikipedia:C (programming language)|C]], [[wikipedia:C++|C++]] and occasionally [[wikipedia:Assembly language|ASM]]. There are various online tutorials and books available to learn these languages.<br />
The Programmers Notepad is (optionally) installed by the devkitPro installer.
+
Alternatively, you can also write homebrew in [[wikipedia:Lua (programming language)|Lua]] by using [[Lua Player Plus]].
 +
 
 +
== Install devkitARM ==
 +
 
 +
=== Windows ===
 +
Use the [http://sourceforge.net/projects/devkitpro/files/Automated%20Installer/ automated-installer]. Install in C:\devkitPro\ and it will install all the latest versions of the required programs (you can disable devkitPSP, but be sure to enable libctru in devkitARM menu). It will create the environment variables automatically.
 +
 
 +
=== Linux / Mac OSX ===
 +
1) Open a terminal and execute these commands:
 +
wget http://sourceforge.net/projects/devkitpro/files/Automated%20Installer/devkitARMupdate.pl
 +
chmod +x devkitARMupdate.pl
 +
sudo ./devkitARMupdate.pl /opt/devkitPro
 +
echo "export DEVKITPRO=/opt/devkitPro" >> ~/.bashrc
 +
echo "export DEVKITARM=\$DEVKITPRO/devkitARM" >> ~/.bashrc
 +
echo "export PATH=\$PATH:\$DEVKITARM/bin" >> ~/.bashrc
 +
source ~/.bashrc
 +
 
 +
=== Install libraries ===
 +
You may want to install various [[List of 3DS development tools#Libraries and tools|libraries/tools]] if your project requires them.
 +
 
 +
== Compiling sources ==
 +
If you simply want to compile a homebrew project without (or after) editing it, you can use the <code>make</code> utility from the command prompt/terminal.
 +
 
 +
1) Windows: Open a Command Prompt (Run -> cmd); Linux/Mac OSX: Open a Terminal from your applications
 +
 
 +
2) Navigate to the project directory (change to the correct path)
 +
cd c:\path\to\your\project
 +
 
 +
3) Run make
 +
make
 +
 
 +
If you ever want to remove the compiled files, you can use this command:
 +
make clean
 +
 
 +
This is often needed when re-compiling a project.
 +
 
 +
=== Troubleshooting ===
 +
It is possible that sometimes your project will not compile. This can have various causes, for example missing libraries. In order to find out the problem, look into the output for the lines that start with "<code>error:</code>"; those will tell you what the problem is. You can ignore the warnings, they do not cause the compilation to fail.
 +
 
 +
If the output is big, you can filter it:
 +
make | grep error
 +
 
 +
If you can't figure out what's wrong, feel free to make a post [https://gbatemp.net/threads/homebrew-development.360646/ on the forums] about it. Make sure to post ''all'' of the error output.
 +
 
 +
Windows Tip: To copy from your command prompt, right click and choose Mark. Then select the text to copy and press the Enter key.
 +
 
 +
==== Common errors ====
 +
;cannot find 3dsx_crt0.o&#58; No such file or directory
 +
:In your makefile, find <code>-mfloat-abi=softfp</code> and change it to <code>-mfloat-abi=hard</code>. You shouldn't ever use <code>softfp</code> for 3DS homebrew.
 +
 
 +
;(name) uses VFP register arguments but (name2) does not
 +
:Part of your project or the libraries you use were compiled with <code>-mfloat-abi=softfp</code> while other parts were compiled with <code>-mfloat-abi=hard</code>. Make sure to use <code>-mfloat-abi=hard</code> everywhere. You may have to manually recompile the libraries you use, if needed.
 +
 
 +
;(command) is not recognized as an internal or external command...
 +
:Your PATH environment variable is not set up correctly. It should contain the msys folder in your devkitPro installation path (eg. <code>C:\devkitPro\msys</code>). Edit your PATH environment variable and make sure it includes this directory. If the command is <code>python</code>, make sure the python install directory (eg. <code>C:\PythonXX</code>, where XX is the version you installed) is in your PATH as well.
 +
 
 +
;unknown field 'rmdir_r' specified in initializer
 +
:Your devkitARM is out of date. Rerun the installer or script.
 +
 
 +
;<nowiki>make[1]: *** No rule to make target `/c/Users/***/path/to'.  Stop.</nowiki>
 +
:Move the project to a folder with no spaces anywhere in its path
 +
 
 +
== SMDH ==
 +
Every homebrew application has an smdh file, containing additional information:
 +
* Icon
 +
* Name of the application (Short description)
 +
* Description of the application (Long description)
 +
* Name of the author (Publisher)
 +
This information is used in [[The Homebrew Launcher]] (3DSX), and in the home menu (3DS/CIA).
 +
 
 +
The icon is a simple 48x48px png file. You can place this png in your project folder (the same folder as your Makefile is in) and name it icon.png. If no icon.png is present, a default icon from the ctrulib folder will be used.
 +
 
 +
The other data can be set in the Makefile directly:
 +
APP_TITLE        := My Application
 +
APP_DESCRIPTION  := A description of my app
 +
APP_AUTHOR      := Me
 +
 
 +
The SMDH file is automatically created when building the project (unless you explicitly set NO_SMDH in the Makefile).
 +
 
 +
You can also manually build the SMDH using [[bannertool]] by [[User:steveice10|steveice10]]:
 +
bannertool makesmdh -s "My application" -l "A description of my app" -p "Me" -i icon.png -o myapplication.smdh
 +
 
 +
== Editor setup ==
 +
This section explains how to set up various editors to edit and compile (existing) homebrew projects. If you want to start a new homebrew project, you should preferably copy an example project and edit the sources.
 +
 
 +
Note that this section lists only the more advanced editors which have features such as code auto-completion. You can use any text editor to edit the source files and compile as detailed above. You should however use a proper code editor (aka not notepad). Some examples are [https://notepad-plus-plus.org/ Notepad++], [http://www.sublimetext.com/ Sublime Text], [http://www.vim.org/ vim], and [https://www.gnu.org/software/emacs/ Emacs].
 +
 
 +
=== Programmer's Notepad ===
 +
The Programmer's Notepad is (optionally) installed by the devkitPro installer.
  
 
1) File -> New -> Project<br />
 
1) File -> New -> Project<br />
Line 29: Line 112:
 
Make sure the project you want to build is the active project (Right click project -> active project)
 
Make sure the project you want to build is the active project (Right click project -> active project)
  
==== Visual Studio 2015 (community) ====
+
=== Visual Studio 2015 (community) ===
 
When installing Visual Studio, make sure to install the Visual C++ packages!
 
When installing Visual Studio, make sure to install the Visual C++ packages!
  
Line 66: Line 149:
 
9) You can now build the project (Right click -> Build)
 
9) You can now build the project (Right click -> Build)
  
==Launcher.dat and .3ds homebrew==
+
=== Eclipse CDT ===
If you don't need Kernel access, prefer developing homebrew in 3dsx format. Remember that the .dat format works only on 4.1.x-4.5.x consoles.
+
Tested with the standalone Eclipse Mars CDT on Linux. Instructions may be slightly different for other cases. Another alternate guide can also be found [https://github.com/wedr2/Guide/wiki/Setting-up-3DS-Homebrew-development-environment-using-Eclipse-CDT-for-C-and-CPP here].
 +
 
 +
1) File -> New -> Makefile Project with Existing Code
 +
 
 +
2) Under Existing Code Location, navigate to the folder containing the code.<br />
 +
You can leave both C and C++ checked, even if the project only contains one.<br />
 +
Under Toolchain for Indexer Settings, choose a valid Toolchain (eg. Linux GCC)
 +
 
 +
3) Right click the Project in the project explorer and choose properties.
 +
 
 +
4) Go to C/C++ Build -> Environment.<br />
 +
Here you need to add the DEVKITPRO and DEVKITARM variables, with their correct paths, eg.
 +
{| class="wikitable"
 +
!Name
 +
!Value
 +
|-
 +
|<code>DEVKITPRO</code>
 +
|<code>/opt/devkitPro</code>
 +
|-
 +
|<code>DEVKITARM</code>
 +
|<code>/opt/devkitPro/devkitARM</code>
 +
|}
 +
 
 +
Make sure to change the values to the paths on your system.
 +
 
 +
5) This step isn't needed to build, but it will make Eclipse recognize the external libraries when editing code.
 +
Go to C/C++ General -> Paths & Symbols -> Includes<br />
 +
Under "GNU C" (or "GNU C++", or both, depending on what files your project has), add the following include directories:
 +
/opt/devkitPro/devkitARM/include
 +
/opt/devkitPro/libctru/include
 +
 
 +
Again, change the paths if needed. When finished, click OK.
 +
 
 +
6) You can now build the project. Right click project -> Build project
 +
 
 +
=== Code::Blocks ===
 +
This premade project can be used as a base https://github.com/TricksterGuy/3ds-template
 +
 
 +
1) Open the project within Code::Blocks<br />
 +
2) Choose File > Save project as template, and choose a name for the template<br />
 +
3) When creating a new project, choose File > New > From template...<br />
 +
4) In the dialog select the template you created in 2)<br />
 +
5) Choose a directory to put the project<br />
 +
6) To build the 3dsx file choose target 3dsx and click the build (gear) button<br />
 +
7) To build and run your homebrew in citra choose the citra target and hit the build button (only works if citra is installed and in your PATH).<br />
 +
 
 +
== 3dsx homebrew ==
 +
Homebrew in this format is the most common, and can be played with ninjhax/ironhax/tubehax. No additional steps have to be taken to create this kind of homebrew; it is the default format produced when using <code>make</code>.
 +
 
 +
Homebrew examples: https://github.com/devkitPro/3ds-examples
 +
 
 +
== 3ds/cia homebrew ==
 +
If you don't need Kernel access, prefer developing homebrew in 3dsx format.
 +
 
 +
After building the project (see above), you should have an .elf file. You can convert this into a .3ds/.cia file with makerom:
 +
* Download [http://3dbrew.org/wiki/Makerom makerom] (and compile it with <code>make</code> if needed)
 +
* Add the folder where you placed the makerom executable to your PATH environment variable
 +
 
 +
To create a .3ds or .cia file, you need some additional files in your project:
 +
* An RSF file - Contains various info such as permissions etc. ('''TODO: Make guide on how to create these''')
 +
* An icon.bin - The icon and information for the home menu. This is equivalent to the compiled SMDH file, so you can just use that one.
 +
* A banner.bin - The banner for the top screen
 +
You should preferably put them in your project folder (or a subfolder).
 +
 
 +
=== Banner ===
 +
Homebrew in 3DS or CIA format requires a banner, which appears on the top screen in the Home menu.
 +
 
 +
The banner consists of an image and an audio file. The image should be a 256x128px png file. This image may contain transparent parts. The audio file is a 16bit wav file.
 +
 
 +
You can create the banner.bin using [[bannertool]] by [[User:Steveice10|Steveice10]]:
 +
bannertool makebanner -i banner.png -a banner.wav -o banner.bin
 +
 
 +
=== Convert .elf to .3ds ===
 +
Run the following commands:
 +
arm-none-eabi-strip [ELF file]
 +
makerom -f cci -o [Destination .3ds file] -rsf [RSF file] -target d -exefslogo -elf [ELF file] -icon [icon file] -banner [banner file]
 +
For example:
 +
arm-none-eabi-strip myproject.elf
 +
makerom -f cci -o myproject.3ds -rsf gw_workaround.rsf -target d -exefslogo -elf myproject.elf -icon myproject.smdh -banner banner.bin
 +
 
 +
Please note that the first command will alter the ELF file, so you may want to back it up first.
 +
 
 +
=== Convert .elf to .cia ===
 +
CIA files are generic data containers that can be installed on a 3DS. In order to do this you need to have a 3DS below 9.2.
 +
 
 +
The process of building a CIA is similar to building a .3DS file:
 +
arm-none-eabi-strip myproject.elf
 +
makerom -f cia -o myproject.cia -rsf cia.rsf -target t -exefslogo -elf myproject.elf -icon myproject.smdh -banner banner.bin
 +
 
 +
Note that the used RSF file is ''not'' the same one as the one used for building .3DS files.
 +
 
 +
== Releasing ==
 +
When you are ready to release your homebrew application, create a new thread in the [https://gbatemp.net/forums/3ds-homebrew-development-and-emulators.275/ Homebrew Development] section. In this thread, you can describe your project.
 +
 
 +
Make sure to attach (or link to an uploaded version of) the relevant files for your homebrew. This will usually be the 3DSX and SMDH files that have been compiled. You can also include the ELF file, which will allow people to repack it with makerom to a 3DS (and CIA) file. The ELF file can also be used on 3DS Emulators (currently two available: [http://gbatemp.net/threads/citra-new-3ds-emulator.365154/ Citra] and [http://gbatemp.net/threads/3dmoo-new-3ds-emulator.366138/ 3DMoo]).
 +
 
 +
If your project is open source, you can upload the code to GitHub. Alternatively, you can simply provide the source as a separate download, or include it with the compiled files.
 +
 
 +
==Using git==
 +
git is a distributed version control system. This allows you to put your code into a repository, which can then be shared with others. The main advantage is that you can keep track of your (and others') changes and even revert them if needed.
 +
 
 +
You can find instructions on the [https://git-scm.com/book/en/v2/Getting-Started-Installing-Git git website] on how to install git on your system.
 +
 
 +
After git is installed on your system, you need to setup your username and email address. This allows git to identify who made the changes. If you have a GitHub account, use the same username and email as there!
 +
 
 +
Open a command prompt (Windows) or Terminal (Linux/OSX) and use the following commands:
 +
git config --global user.name "yournamehere"
 +
git config --global user.email "youremail@address.here"
  
The guide to setup a 3ds homebrew environment is old and need to be rewritten.
+
===Getting started===
 +
1) If you have not yet done so, create a file named <code>README.md</code> in your project folder. You can use this file to add a description and information of your project. This description will be shown when people view your repository on GitHub. You can use [https://help.github.com/articles/markdown-basics/ markdown] to add formatting such as bold and headings.
  
'''Please rewrite a guide here.'''
+
2) Open a command prompt (Windows) or Terminal (Linux/OSX).
  
===Development environment===
+
3) Navigate to your project folder
If you already installed Devkit ARM with CTRuLib, you don't need to follow the installations steps, unless you want to compile using Python instead of Makefile.
+
cd c:/path/to/your/project
  
====Install Python 2.7.x====
+
4) Initialize it as a git repository
Note: You can skip this step if you want. Go to step 2. directly if you don't want to use Python to compile your homebrew.
+
git init
  
* [https://www.python.org/downloads/ Download] the latest version of Python 2.7.x
+
5) Add your existing code to the repository (note: the <code>.</code> is part of the command)
* Install Python on your computer.
+
  git add .
* If you are on Linux, add Python to your environment variable $PATH
+
* If you are on Windows, install it in C:\Python27\, and it should edit the environment variable "Path" automatically.  
+
If you need to do it manually, follow these steps:
+
* Go to My Computer > Right-click > Properties > Advanced tab > Environment variables > System variables
+
* In the list search for "Path", select it and press Edit/Modify
+
* At the end of the line, add this:
+
  ;C:\Python27
+
It will allow you to call the Python program from any place by typing "Python" in a command line window.
+
  
====Install a compiler====
+
6) Do the initial commit
* Install DevkitPro + DevkitARM + CTRULib by following [http://sourceforge.net/projects/devkitpro/files/Automated%20Installer/ this guide] if you are using Linux or Mac.
+
  git commit -m "Initial commit"
* If you are using Windows, use the [http://sourceforge.net/projects/devkitpro/files/Automated%20Installer/ automated-installer]. Install in C:\devkitPro\ and it will install all the latest versions of the required programs (you can disable DevKit PSP, but be sure to enable CTRULib in DevkitARM menu). It will create the environment variables automatically.
+
  
You can install and use [https://launchpad.net/gcc-arm-embedded GNU Tools for ARM Embedded Processors] as alternate compiler, but it will not be enough to develop ARM11 homebrew as you will need additional libraries provided by DevkitPro.
+
===Committing===
If you use this compiler for ARM9 homebrew, you will also need to add the ARM binaries path to your environment variables. Follow the previous Python steps to add this path:
+
When you make changes to your code, they need to be committed in order to "save" them to your git repository. When and how often you commit is up to you, but try to do at most one major change per commit.
;C:\Program Files\GNU Tools ARM Embedded\''4.8 2013q4''\bin
+
Attention, change the version in the path, do not keep ''4.8 2013q'' but use the one you installed instead.
+
  
====Build script====
+
1) Make the repository aware of your changes
To compile your homebrew sources to an executable binary file you can use either a Python script or a Makefile script.
+
git add -A
Makefile is easier, but this guide will also detail how the Python package is created to cover and understand all installation steps.
+
  
There are two packages ready to download: One for [http://gbatemp.net/attachments/3ds_homebrew_demo-zip.5947/ Python] and one for [http://gbatemp.net/attachments/3ds_homebrew_makefileedition-zip.5960/ Makefile], both made by [[Snailface]].
+
2) Add them to a commit
Just download the one you want and extract it in any folder. This will become your homebrew working folder.
+
git commit -m "Message of your commit (eg. describe your changes)"
Create one copy per homebrew you are developing.
+
  
This is how the Python package has been created:
+
===Add your project to GitHub===
* Download the files from [https://github.com/insaneKane/3DS_Homebrew_Stuff2 Kane49's github], and extract to a folder of your choice.
+
GitHub is a popular host for online git repositories.
* Download the files from [https://github.com/naehrwert/p3ds Naehrwert's gitHub], and extract the files and the folder into the p3ds folder from the previous download.
+
* For Linux users, download the modified [https://www.dropbox.com/s/jyzhkk9giy1saq0/build.py.zip build.py] file from [[Tomiga]] to replace the one you downloaded from Kane49's repository.
+
* Open build.by and replace both instances of:
+
"-mcpu=mpcore -march=armv6k"
+
to
+
"-mcpu=arm946e-s -march=armv5te".
+
* Comment the lines:
+
#run("copy Launcher.dat E:\\Launcher.dat > NUL")
+
#upload("Launcher.dat")
+
#run("del payload.bin")
+
  
===Compiling .dat format===
+
1) [https://github.com/new Create a GitHub repository].<br />
====ARM9====
+
Make sure to name the repository after your project and optionally give it a description. Make sure the checkbox to create a README is ''not'' checked. The <code>.gitignore</code> and <code>license</code> should also be set to <code>None</code>
If you are using Python to compile your homebrew:
+
* In your development folder, open a command line and type "Python build.py"
+
* You can also run Build.bat
+
  
If you are using makefile:
+
2) Open a command prompt (Windows) or Terminal (Linux/OSX) and navigate to your project folder.
* In your development folder, open a command line and type "make"
+
* You can also run Build.bat
+
  
Your homebrew will be compiled as a Payload.bin and will be encapsulated into a Launcher.dat file ready to launch using a ROP exploit.
+
3) Add GitHub as a remote host (change the URL):
You can provide both the .bin and .dat file when you share your homebrew.
+
git remote add origin <nowiki>https://github.com/yourname/yourrepository.git</nowiki>
  
====ARM11====
+
4) From now on, you can <code>push</code> your changes to GitHub with the following command:
* Open a command line window and navigate to your homebrew folder and type "make".
+
git push origin master
It will create a <folder name of your project>.elf file.
+
This pushes the <code>master</code> branch to the remote called <code>origin</code>, which we setup as GitHub.
  
To convert the elf file to .3ds format:
+
You don't have to push after every commit, but your changes will only show up on GitHub after you push.
  
* Download [http://3dbrew.org/wiki/Makerom MakeROM] by [[3DSGuy]].
+
===Tags===
* [http://www.mediafire.com/download/4ckk6tmqcq11rai/CTR.zip Alternative Download Link]
+
Tags are a way on git to mark specific commits as special. For example, you could use them to track your major releases.
* Extract it to a new folder.
+
* If you don't want to make homebrew for Gateway 3DS flashcart, you can find file requirement and command line format to use with MakeROM on [http://3dbrew.org/wiki/Makerom 3dbrew.org].
+
  
===converting .elf to .3ds format===
+
1) Create the tag
* If you want to make the .3ds file working on Gateway 3DS flashcart homebrew menu, download the [https://www.dropbox.com/s/emnre6pyz2e6j7j/gwcardhbfiles.zip Gateway Card Homebrew Files], by [[3DSGuy]], and extract its content into the Makerom folder.
+
git tag -a tagname -m "description here"
* Open a command line window and navigate to the MakeROM folder.
+
For example:
* type
+
  git tag -a v1.0 -m "My first release!"
  build <elf file> <output 3ds file>
+
To tag an older commit, specify the sha1 hash of the commit:
where <elf.file> is the name of your homebrew.elf, and <output 3ds file> is the name of the .3ds file
+
git tag -a tagname sha1 -m "description here"
  
example
+
2) If you are using GitHub, you must manually push the tag:
  build myproject.elf AwesomeGame.3ds
+
  git push origin tagname
  
===Making your own Homebrew Icon and Banner===
+
[[Category:Nintendo 3DS|Homebrew Development]]
If you want to create your own banner and icon for ARM11 homebrew, you can use [[3DS Banner Maker]], by [[Snailface]], to convert png pictures to the correct format used by MakeROM.
+
[[Category:3DS Homebrew| Development]]
It requires Python 2 and PIL (Python Image Library).
+

Latest revision as of 20:28, 25 February 2017

This page contains general information for 3DS Homebrew developers.

If you have any questions, you can come to GBAtemp's main homebrew development and help thread. It contains shared sources, examples and libraries.

You can find all known resources (hardware registers, syscalls, utilities) to develop your homebrew on 3dbrew.

To develop 3DS homebrew you need a development environment consisting of tools, scripts and libraries which will be detailed below. The sources are compiled to binary using GNU GCC-ARM or devkitPro with devkitARM. The available tools and SDK work on Windows 32/64bit and Linux.

The languages used to write homebrew are C, C++ and occasionally ASM. There are various online tutorials and books available to learn these languages.
Alternatively, you can also write homebrew in Lua by using Lua Player Plus.

Install devkitARM

Windows

Use the automated-installer. Install in C:\devkitPro\ and it will install all the latest versions of the required programs (you can disable devkitPSP, but be sure to enable libctru in devkitARM menu). It will create the environment variables automatically.

Linux / Mac OSX

1) Open a terminal and execute these commands:

wget http://sourceforge.net/projects/devkitpro/files/Automated%20Installer/devkitARMupdate.pl
chmod +x devkitARMupdate.pl
sudo ./devkitARMupdate.pl /opt/devkitPro
echo "export DEVKITPRO=/opt/devkitPro" >> ~/.bashrc
echo "export DEVKITARM=\$DEVKITPRO/devkitARM" >> ~/.bashrc
echo "export PATH=\$PATH:\$DEVKITARM/bin" >> ~/.bashrc
source ~/.bashrc

Install libraries

You may want to install various libraries/tools if your project requires them.

Compiling sources

If you simply want to compile a homebrew project without (or after) editing it, you can use the make utility from the command prompt/terminal.

1) Windows: Open a Command Prompt (Run -> cmd); Linux/Mac OSX: Open a Terminal from your applications

2) Navigate to the project directory (change to the correct path)

cd c:\path\to\your\project

3) Run make

make

If you ever want to remove the compiled files, you can use this command:

make clean

This is often needed when re-compiling a project.

Troubleshooting

It is possible that sometimes your project will not compile. This can have various causes, for example missing libraries. In order to find out the problem, look into the output for the lines that start with "error:"; those will tell you what the problem is. You can ignore the warnings, they do not cause the compilation to fail.

If the output is big, you can filter it:

make | grep error

If you can't figure out what's wrong, feel free to make a post on the forums about it. Make sure to post all of the error output.

Windows Tip: To copy from your command prompt, right click and choose Mark. Then select the text to copy and press the Enter key.

Common errors

cannot find 3dsx_crt0.o: No such file or directory
In your makefile, find -mfloat-abi=softfp and change it to -mfloat-abi=hard. You shouldn't ever use softfp for 3DS homebrew.
(name) uses VFP register arguments but (name2) does not
Part of your project or the libraries you use were compiled with -mfloat-abi=softfp while other parts were compiled with -mfloat-abi=hard. Make sure to use -mfloat-abi=hard everywhere. You may have to manually recompile the libraries you use, if needed.
(command) is not recognized as an internal or external command...
Your PATH environment variable is not set up correctly. It should contain the msys folder in your devkitPro installation path (eg. C:\devkitPro\msys). Edit your PATH environment variable and make sure it includes this directory. If the command is python, make sure the python install directory (eg. C:\PythonXX, where XX is the version you installed) is in your PATH as well.
unknown field 'rmdir_r' specified in initializer
Your devkitARM is out of date. Rerun the installer or script.
make[1]: *** No rule to make target `/c/Users/***/path/to'. Stop.
Move the project to a folder with no spaces anywhere in its path

SMDH

Every homebrew application has an smdh file, containing additional information:

  • Icon
  • Name of the application (Short description)
  • Description of the application (Long description)
  • Name of the author (Publisher)

This information is used in The Homebrew Launcher (3DSX), and in the home menu (3DS/CIA).

The icon is a simple 48x48px png file. You can place this png in your project folder (the same folder as your Makefile is in) and name it icon.png. If no icon.png is present, a default icon from the ctrulib folder will be used.

The other data can be set in the Makefile directly:

APP_TITLE        := My Application 
APP_DESCRIPTION  := A description of my app
APP_AUTHOR       := Me

The SMDH file is automatically created when building the project (unless you explicitly set NO_SMDH in the Makefile).

You can also manually build the SMDH using bannertool by steveice10:

bannertool makesmdh -s "My application" -l "A description of my app" -p "Me" -i icon.png -o myapplication.smdh

Editor setup

This section explains how to set up various editors to edit and compile (existing) homebrew projects. If you want to start a new homebrew project, you should preferably copy an example project and edit the sources.

Note that this section lists only the more advanced editors which have features such as code auto-completion. You can use any text editor to edit the source files and compile as detailed above. You should however use a proper code editor (aka not notepad). Some examples are Notepad++, Sublime Text, vim, and Emacs.

Programmer's Notepad

The Programmer's Notepad is (optionally) installed by the devkitPro installer.

1) File -> New -> Project
Give it a name and save anywhere.

2) Right click the project -> Add Files
Now navigate to the example you want and add the files from that folder (eg. Makefile, readme.md, ...)

3) Right click the project -> Add Magic Folder
Navigate to the example directory again and add the source folder within. Repeat this for any other folders in the example (if any).

4) You can build the project using Tools -> Make
Make sure the project you want to build is the active project (Right click project -> active project)

Visual Studio 2015 (community)

When installing Visual Studio, make sure to install the Visual C++ packages!

1) File -> New -> Project From Existing Code...

2) In the dropdown, choose Visual C++ and click Next

3) Under Project file location, navigate to the folder with all sources. Enter a name for the project and click next.

4) Use external build system, Next

5) Build command line:

make

Clean command line:

make clean

Leave the rest blank. Click Finish.

6) Right click project (in the solution explorer) -> properties

7) Under VC++ directories -> General -> Include directories, add the devkitARM and ctrulib include directories (change if needed):

C:\devkitPro\devkitARM\include
C:\devkitPro\libctru\include

Make sure not to remove anything already in the box! You can add any other include folder that the project may need as well. In the end it'll read something like:

C:\devkitPro\devkitARM\include;C:\devkitPro\libctru\include;$(IncludePath)

Click OK

8) (Optional) Right click project -> Add -> Existing Item
Choose the Makefile and any other files you want to add, then click Add. This step isn't required, but allows you to edit the Makefile etc. from the editor.

Alternatively, you can use "Show All Files" under the "Project" menu (on the top) to display all files and folders as they are on the file system.

9) You can now build the project (Right click -> Build)

Eclipse CDT

Tested with the standalone Eclipse Mars CDT on Linux. Instructions may be slightly different for other cases. Another alternate guide can also be found here.

1) File -> New -> Makefile Project with Existing Code

2) Under Existing Code Location, navigate to the folder containing the code.
You can leave both C and C++ checked, even if the project only contains one.
Under Toolchain for Indexer Settings, choose a valid Toolchain (eg. Linux GCC)

3) Right click the Project in the project explorer and choose properties.

4) Go to C/C++ Build -> Environment.
Here you need to add the DEVKITPRO and DEVKITARM variables, with their correct paths, eg.

Name Value
DEVKITPRO /opt/devkitPro
DEVKITARM /opt/devkitPro/devkitARM

Make sure to change the values to the paths on your system.

5) This step isn't needed to build, but it will make Eclipse recognize the external libraries when editing code. Go to C/C++ General -> Paths & Symbols -> Includes
Under "GNU C" (or "GNU C++", or both, depending on what files your project has), add the following include directories:

/opt/devkitPro/devkitARM/include
/opt/devkitPro/libctru/include

Again, change the paths if needed. When finished, click OK.

6) You can now build the project. Right click project -> Build project

Code::Blocks

This premade project can be used as a base https://github.com/TricksterGuy/3ds-template

1) Open the project within Code::Blocks
2) Choose File > Save project as template, and choose a name for the template
3) When creating a new project, choose File > New > From template...
4) In the dialog select the template you created in 2)
5) Choose a directory to put the project
6) To build the 3dsx file choose target 3dsx and click the build (gear) button
7) To build and run your homebrew in citra choose the citra target and hit the build button (only works if citra is installed and in your PATH).

3dsx homebrew

Homebrew in this format is the most common, and can be played with ninjhax/ironhax/tubehax. No additional steps have to be taken to create this kind of homebrew; it is the default format produced when using make.

Homebrew examples: https://github.com/devkitPro/3ds-examples

3ds/cia homebrew

If you don't need Kernel access, prefer developing homebrew in 3dsx format.

After building the project (see above), you should have an .elf file. You can convert this into a .3ds/.cia file with makerom:

  • Download makerom (and compile it with make if needed)
  • Add the folder where you placed the makerom executable to your PATH environment variable

To create a .3ds or .cia file, you need some additional files in your project:

  • An RSF file - Contains various info such as permissions etc. (TODO: Make guide on how to create these)
  • An icon.bin - The icon and information for the home menu. This is equivalent to the compiled SMDH file, so you can just use that one.
  • A banner.bin - The banner for the top screen

You should preferably put them in your project folder (or a subfolder).

Homebrew in 3DS or CIA format requires a banner, which appears on the top screen in the Home menu.

The banner consists of an image and an audio file. The image should be a 256x128px png file. This image may contain transparent parts. The audio file is a 16bit wav file.

You can create the banner.bin using bannertool by Steveice10:

bannertool makebanner -i banner.png -a banner.wav -o banner.bin

Convert .elf to .3ds

Run the following commands:

arm-none-eabi-strip [ELF file]
makerom -f cci -o [Destination .3ds file] -rsf [RSF file] -target d -exefslogo -elf [ELF file] -icon [icon file] -banner [banner file]

For example:

arm-none-eabi-strip myproject.elf
makerom -f cci -o myproject.3ds -rsf gw_workaround.rsf -target d -exefslogo -elf myproject.elf -icon myproject.smdh -banner banner.bin

Please note that the first command will alter the ELF file, so you may want to back it up first.

Convert .elf to .cia

CIA files are generic data containers that can be installed on a 3DS. In order to do this you need to have a 3DS below 9.2.

The process of building a CIA is similar to building a .3DS file:

arm-none-eabi-strip myproject.elf
makerom -f cia -o myproject.cia -rsf cia.rsf -target t -exefslogo -elf myproject.elf -icon myproject.smdh -banner banner.bin

Note that the used RSF file is not the same one as the one used for building .3DS files.

Releasing

When you are ready to release your homebrew application, create a new thread in the Homebrew Development section. In this thread, you can describe your project.

Make sure to attach (or link to an uploaded version of) the relevant files for your homebrew. This will usually be the 3DSX and SMDH files that have been compiled. You can also include the ELF file, which will allow people to repack it with makerom to a 3DS (and CIA) file. The ELF file can also be used on 3DS Emulators (currently two available: Citra and 3DMoo).

If your project is open source, you can upload the code to GitHub. Alternatively, you can simply provide the source as a separate download, or include it with the compiled files.

Using git

git is a distributed version control system. This allows you to put your code into a repository, which can then be shared with others. The main advantage is that you can keep track of your (and others') changes and even revert them if needed.

You can find instructions on the git website on how to install git on your system.

After git is installed on your system, you need to setup your username and email address. This allows git to identify who made the changes. If you have a GitHub account, use the same username and email as there!

Open a command prompt (Windows) or Terminal (Linux/OSX) and use the following commands:

git config --global user.name "yournamehere"
git config --global user.email "[email protected]"

Getting started

1) If you have not yet done so, create a file named README.md in your project folder. You can use this file to add a description and information of your project. This description will be shown when people view your repository on GitHub. You can use markdown to add formatting such as bold and headings.

2) Open a command prompt (Windows) or Terminal (Linux/OSX).

3) Navigate to your project folder

cd c:/path/to/your/project

4) Initialize it as a git repository

git init

5) Add your existing code to the repository (note: the . is part of the command)

git add .

6) Do the initial commit

git commit -m "Initial commit"

Committing

When you make changes to your code, they need to be committed in order to "save" them to your git repository. When and how often you commit is up to you, but try to do at most one major change per commit.

1) Make the repository aware of your changes

git add -A

2) Add them to a commit

git commit -m "Message of your commit (eg. describe your changes)"

Add your project to GitHub

GitHub is a popular host for online git repositories.

1) Create a GitHub repository.
Make sure to name the repository after your project and optionally give it a description. Make sure the checkbox to create a README is not checked. The .gitignore and license should also be set to None

2) Open a command prompt (Windows) or Terminal (Linux/OSX) and navigate to your project folder.

3) Add GitHub as a remote host (change the URL):

git remote add origin https://github.com/yourname/yourrepository.git

4) From now on, you can push your changes to GitHub with the following command:

git push origin master

This pushes the master branch to the remote called origin, which we setup as GitHub.

You don't have to push after every commit, but your changes will only show up on GitHub after you push.

Tags

Tags are a way on git to mark specific commits as special. For example, you could use them to track your major releases.

1) Create the tag

git tag -a tagname -m "description here"

For example:

git tag -a v1.0 -m "My first release!"

To tag an older commit, specify the sha1 hash of the commit:

git tag -a tagname sha1 -m "description here"

2) If you are using GitHub, you must manually push the tag:

git push origin tagname