Homebrew development guide

From WiiUBrew
Jump to: navigation, search

Please keep in mind the following:

Currently, we have user and kernel-level code execution on the main CPU. We are working on documenting the user mode API and reverse engineering the rest of the system, including the security OS. Exploits are on Github.

This article will go over the primary ways of developing various types of Homebrew on the Wii U.


Configuring environment

A linux-esque environment is recommended. Your first step is to install devkitPPC, which you can do by following the steps for your Operating System on that link. You only have to setup devkitPPC, and should not install the gamecube/wii/libogc libraries. Instead, you should install Dimok's libogc and portlibs.

Making HBL Apps

The Homebrew Launcher is an easy platform to target for development. The two below methods are useful for making console and GUI apps respectively. In particular, lib_easy is a good place to start. Apps compiled with this method are in the ELF format.

Using lib_easy

lib_easy by rw-r-r_0644 was designed to be a quick way to get familiar with programming on the Wii U. That link contains an example hello world project. After setting up your environment, you can compile the hello world project by cd-ing into the folder and running "make".

An example of a homebrew app that was made using lib_easy is UClick.

Using Dimok's libraries

Dimok's libraries provide assistance with interacting with various parts of the Wii U. For some projects that use OSScreen to interact with the see Pong, C@ve, Snake, or Space Game. (Specifically, you will want to look at this HBL pong port).

Dimok's libs also provide many GX2 wrappers that provide a template for creating Homebrew Launcher-style GUIs. Examples of projects that utilize this include Homebrew Launcher, CHIP-8_Emulator, and Homebrew App Store.

Making Native Apps

There's a work in progress Wii U Toolchain (also called "wut") that can be used to make native RPX apps. These would be able to be installed to the System if not for the heavy signature checking that the Wii U performs on the System menu. In the long run, these may be preferable to the HBL-style ELF launching system.

Wut is under active development. It provides instructions on how to get started in its readme along with a Hello World. There are a few apps out that make use of wut, including gx2texture2d and ports of Pong and Space Game. Although it is under development, it is still fairly featured. RPX files that are compiled with wut can also be played in decaf-emu.

Making Userland Apps

The userland environment does not require a kernel exploit to execute programs, but as a result is heavily limited. These apps hijack the browser, but don't go any further. libwiiu is a good build system to use to produce .bin files which can be converted into mp4 payloads. It has detailed compilation instructions and many examples in the readme and repository.

A lot of the earlier homebrew was initially made for this userland environment, although most of it has since been ported to HBL. [Pong], [C@ve], and [Space Game] are among those early apps.

It isn't really recommended to use userland while a kernel exploit environment is available. It is heavily restricted to ~20KB payload files, no access to global variables, and no access to GX2 (OSScreen only).


QuarkTheAwesome is working on a more in-depth guide to Wii U development, which is available here.

He has also produced an older, outdated development guide for the userspace environment here.


If you need help developing, here are a few IRC channels that may be able to provide direct assistance.

Don't be afraid to ask! :)

Personal tools