Difference between revisions of "3DS Homebrew Development"

Revision as of 21:47, 23 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.

Compiling sources

If you simply want to compile a homebrew project without 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

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

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).

Examples

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.

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.

The guide to setup a 3ds homebrew environment is old and need to be rewritten.

Please rewrite a guide here.

Development environment

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.

Install Python 2.7.x

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.

• Download the latest version of Python 2.7.x
• Install Python on your computer.
• 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

You can install and use 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. 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:

;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

To compile your homebrew sources to an executable binary file you can use either a Python script or a Makefile script. 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 Python and one for Makefile, both made by Snailface. Just download the one you want and extract it in any folder. This will become your homebrew working folder. Create one copy per homebrew you are developing.

This is how the Python package has been created:

• Download the files from Kane49's github, and extract to a folder of your choice.
• Download the files from Naehrwert's gitHub, and extract the files and the folder into the p3ds folder from the previous download.
• For Linux users, download the modified 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

ARM9

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:

• 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. You can provide both the .bin and .dat file when you share your homebrew.

ARM11

• Open a command line window and navigate to your homebrew folder and type "make".

It will create a <folder name of your project>.elf file.

To convert the elf file to .3ds format:

• Download MakeROM by 3DSGuy.
• Alternative Download Link
• 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 3dbrew.org.

converting .elf to .3ds format

• If you want to make the .3ds file working on Gateway 3DS flashcart homebrew menu, download the Gateway Card Homebrew Files, by 3DSGuy, and extract its content into the Makerom folder.
• Open a command line window and navigate to the MakeROM folder.
• type

build <elf file> <output 3ds file>

where <elf.file> is the name of your homebrew.elf, and <output 3ds file> is the name of the .3ds file

example

build myproject.elf AwesomeGame.3ds

Making your own Homebrew Icon and Banner

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. It requires Python 2 and PIL (Python Image Library).