Difference between revisions of "3DS Homebrew Development"

Revision as of 10:46, 26 August 2015

Information for 3DS Homebrew developers.

Install devkitPro

DevkitPro is an essential set of toolchains for homebrew development.

• Linux/Mac OSX: Follow this guide.
• 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 CTRULib in DevkitARM menu). It will create the environment variables automatically.

You may also want to install other 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

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.

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.

Programmers Notepad

The Programmers 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.

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.

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

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.

You can find ctrulib homebrew examples here: https://github.com/smealum/ctrulib/tree/master/examples

Launcher.dat and .3ds homebrew

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.

Convert .elf to .3ds

To create a .3ds file (or .cia), you need some additional files in your project (TODO: Make guide on how to create these):

• An RSF file - Contains various info
• An icon.bin - The icon for the home menu
• A banner.bin - The banner for the top screen

You should preferably put them in a subfolder (for example "cci") in your project folder.

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

• Download makerom (and compile it with make if needed)
• Add the folder where you placed the makerom executable to your PATH environment variable
• Open a command prompt/terminal and navigate to your project

cd c:/path/to/your/project

• 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 cci/gw_workaround.rsf -target d -exefslogo -elf myproject.elf -icon cci/icon.bin -banner cci/banner.bin

TODO: How to Build a CIA guide

This page may need to be updated with the newest available information.   Please edit the page with new information and remove this Template when finished!

;C:\Python27

;C:\Program Files\GNU Tools ARM Embedded\4.8 2013q4\bin

"-mcpu=mpcore -march=armv6k"

"-mcpu=arm946e-s -march=armv5te". 

#run("copy Launcher.dat E:\\Launcher.dat > NUL")
#upload("Launcher.dat")
#run("del payload.bin")

build <elf file> <output 3ds file>

build myproject.elf AwesomeGame.3ds