Hello everyone!

After a whole week fighting with SDL2 I decided to make a similar tutorial to my first one: https://gbatemp.net/threads/tutoria...for-nintendo-3ds-homebrew-development.461083/
so anyone can easily create stuff for Nintendo Switch.

This tutorial is mainly made for Windows, so there are maybe some things you cannot use on MAC/Linux. Just change those as needed.

There's a simple console tutorial made by @WerWolv, so be sure to check it out here.

Introduction:

This guide shows how to set up the initial Nintendo Switch homebrew development environment using Visual Studio 2017 Community Edition. This guide should also apply to Visual Studio 2017 Professional/Enterprise and up. The last version I tested is Visual Studio 2022 (16/02/2022 . This setup will allow you to use Visual Studio's IntelliSense when working with your code, while being able to compile your code into .NRO files for homebrew applications. We can create .NSP o our homebrews with NRO2NSPBuilder.

By following this guide, you will be creating your own project from scratch in C++. However, should you feel like using a pre-made Visual Studio project template, you may use devkitPro Examples or my own template. If you want a game as reference, check any of my games: Good examples are T-REKT NX or TIL NX which has drag functions.

We will call Visual Studio 2017 Community as "VS2017" from here on out. As I mentioned before, Enterprise and Professional editions can be used as well.

Microsoft Visual C/C++ is not bundled with VS2017 by default. You must choose to install this package, as it is required for Nintendo Switch homebrew development. If you cannot find it in the VS2017 Installer, you can follow the instructions to obtain this package below.

Minum Requirements:

- Latest version of Visual Studio 2017 Community: https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx
- Microsoft Visual C/C++ package for Visual Studio 2017 Community.
- Latest stable version of devkitPro: http://devkitpro.org/wiki/Getting_Started
- Switch packages obtained by pacman packages
- Knowledge in C or C++.
- Creativity and time to make good stuff.

Notes:

To explain the inconsistencies of slashes, "\" and "/", used in this guide:

In Windows, of any editions, it uses backslashes "\" as file separators, and not forward slashes "/". This also means in Visual Studio of any editions, it natively uses backslashes "\" as file separators. If you see forward slashes "/", this clearly means it is used in Makefiles.

The usage of backslashes "\" was due to the forward slashes "/" being used as indicators for "switches" or "flags" (cmd.exe /w, or /help) in IBM software, and is not compatible to parse as file separators. MS-DOS adopted this, and to this day, forward slash switches are still used in many places.

Setup:

Spoiler

1) Acquiring Microsoft Visual C/C++ for VS2017:

- Install VS2017. It will install Visual Studio Installer too.

- Run Visual Studio Installer.

- Click on Modify below VS2017.

- Click on Components > Select C++ components > Install.


VS2017 will then install Visual C/C++ packages. Follow the instructions, then continue to the next section.


2) Nintendo Switch Homebrew Development Setup:

- Install devkitPro, by following the instructions given in the Getting Started article.

- Run Visual Studio 2017 Community.

- On the Start page in VS2017, under the Start section, click "New Project...".

- When in the New Project wizard, click on Installed > Templates > Visual C++ > Makefile Project. It can be in Installed > C++ > MAKE.

- Down at the bottom, choose your project name, your solution location, and the solution action.

NOTE: MAKE SURE your solution location is located in a directory where the file path does NOT contain any WHITESPACES!

- Click OK.

- A new panel will show. Add the commands for Build, Rebuild, and Clean, as follows:

Build-> make
Rebuild-> make clean all
Clean-> make clean


- On the right pane, add the following path to the "Include Search Path":


\path\to\devkitPro\devkitA64\include
\path\to\devkitPro\libnx\include
$(ProjectDir)\include

- Click OK and the project will be setup.


If you want to add more folders to include:

- In the Solution Explorer, right click on your project, and choose Properties.

- On the left pane, click on General.

- Make sure under General, Configuration Type is set to Makefile.

- On the left pane, click on VC++ Directories.

- Under General, click on Include Directories, click on the arrow dropdown button on the right, and select <Edit>.

- Add the desired filepaths.

- Click OK to go back to the VS2017 editor.



- In the Solution Explorer, add a new item under the filter, "Source Files", by right clicking the filter, Add > "New Item...".

- In the Add New Item wizard, click on C++ File.

- Down at the bottom of the wizard, make sure the Location is the following, with the folder, "source" added at the end (And yes, it is all lowercase "source"):

\path\without\whitespace\to\project\source\

- Type your C++ file name (lets call it main.cpp), and click on "Add".
Add the following #if and #defines macros at the top of your CPP file:

#if __INTELLISENSE__
 typedef unsigned int __SIZE_TYPE__;
 typedef unsigned long __PTRDIFF_TYPE__;
 #define __attribute__(q)
 #define __builtin_strcmp(a,b) 0
 #define __builtin_strlen(a) 0
 #define __builtin_memcpy(a,b) 0
 #define __builtin_va_list void*
 #define __builtin_va_start(a,b)
 #define __extension__
 #endif

 #if defined(_MSC_VER)
 #include <BaseTsd.h>
 typedef SSIZE_T ssize_t;
 #endif

Then add the following code to your C++ file after it:

#include <switch.h>
#include <iostream>

int main(int argc, char* argv[])
{
    consoleInit(NULL);

    // Other initialization goes here. As a demonstration, we print hello world.
    std::cout<<"Hello World!\n"<<std::endl;

    // Configure our supported input layout: a single player with standard controller styles
    padConfigureInput(1, HidNpadStyleSet_NpadStandard);

    // Initialize the default gamepad (which reads handheld mode inputs as well as the first connected controller)
    PadState pad;
    padInitializeDefault(&pad);

    // Main loop
    while (appletMainLoop())
    {
        // Scan all the inputs. This should be done once for each frame
        padUpdate(&pad);

        // hidKeysDown returns information about which buttons have been
        // just pressed in this frame compared to the previous one
        u64 kDown = padGetButtonsDown(&pad);

    if (kDown & HidNpadButton_A)
              std::cout<<"Pressed A button!\n"<<std::endl;

        if (kDown & HidNpadButton_Plus)
            break; // break in order to return to hbmenu

        // Your code goes here

        // Update the console, sending a new frame to the display
        consoleUpdate(NULL);
    }

    // Deinitialize and clean up resources used by the console (important!)
    consoleExit(NULL);
    return 0;
}

This is the part where it gets tricky.

Ignore the errors in the Error List by turning it off or clicking "X of X Errors" once, where X is any given number.

If you see any squiggly lines underneath ANY letter or character in the code provide above, it means you have set your IntelliSense incorrectly. Make sure to double check all of the steps above, to see if you have missed any.


Tricky part is finished. Congratulations!

- In File Explorer, navigate to the following directory:

\path\to\devkitPro\examples\switch\templates\application

- Copy the Makefile file.

- In File Explorer, navigate back to your project root directory.

- Paste the Makefile file to the project root directory.

- In VS2017, in the Solution Explorer, right click on your project, Add > "Existing Item...".

- Select Makefile.

- Click on "Add".

- In the Solution Explorer, open the Makefile, so the file is opened in VS2017.

- Edit the name of the homebrew, the creator to fit your project.

- Save Makefile.

- In the Solution Explorer, right click on the Makefile, and select "Properties".

- In the Makefile Property Pages, make sure on the right pane, under General, the Item Type is Text, and the rest of the entries are empty.

- Click OK to exit back to VS2017 editor.

- Hit CTRL+SHIFT+B or in the taskbar, "Build > Build Solution" or "Build > Build [project name]", where [project name] is your project name. You can also click on the green button: Windows Debugger and it will compile too.

- In VS2017, in the Output tab, you should see your code being built via Makefile.

And that's it! From this point on, you are free to add anything you want.

Adding more packages for devkitPro:

Spoiler

We will use some libraries in our homebrews but for sure, we need SDL2. Let's install it!

- First we need to open the command window: Windows + R > cmd or Shift + Right Click > Open CMD Prompt Here

- For displaying the package list (to know package names), just type: pacman -Sl

- Install the packages with: pacman -Syuu [package1] [package2] [every package you want to install...]

Example: pacman -Syuu switch-sdl switch-sdl2_gfx switch-sdl2_image switch-sdl2_ttf switch-sdl2_net switch-sdl2_mixer

You may need to update portlibs by:

pacman -S switch-portlibs

NOTE: You can install as many packages as you need in your homebrew

- Once the packages are installed, to use SDL we need to add to the makefile this line:

LIBS    :=    -lSDL2_ttf -lSDL2_gfx -lSDL2_image -lnx

and if you want to use every library as the template (you need every package installed):

LIBS    :=    -lSDL2_ttf -lSDL2_gfx -lSDL2_image -lSDL2_mixer -lpng -ljpeg -lglad -lEGL -lglapi -ldrm_nouveau -lvorbisidec -logg -lmpg123 -lmodplug -lstdc++ -lavformat -lavcodec -lswresample -lswscale -lavutil -lbz2 -lass -ltheora -lvorbis -lopus `sdl2-config --libs` `freetype-config --libs` -lnx

Using SDL in your project:

We will use NX-Shell's my SDL Helper modification. Let's see how it works:

Spoiler

First, we will download SDL_Helper.hpp, SDL_Helper.cpp, FontCache.c and FontCache.h from my template and place it in our source folder.

Now you can use SDL2. Congrats!

I recommend you to create an SDL_Helper object and send it's pointers.

For that, in the main.cpp copy this at the beggining of the method:

    plInitialize();
    romfsInit();
    SDL_Helper * helper = new SDL_Helper();
    helper->SDL_HelperInit();

For loading an image we will use:

SDL_Texture * myTexture;
helper->SDL_LoadImage(&myTexture, "romfs:/textureSprite.png");

in the main loop, when you need to paint your texture just use:

        helper->SDL_DrawImage(myTexture, x, y);
        helper->SDL_Renderdisplay();

I added rect method for multiple frames:

        helper->SDL_DrawImageRect(myTexture, x, y, xOffset, yOffset, frameWidth, frameHeight);
        helper->SDL_Renderdisplay();

And opacity methods:

        helper->SDL_DrawImageOpacity(myTexture, x, y, opacity);
        helper->SDL_Renderdisplay();

Once we exit the program, we need to delete everything:

    plExit();
    romfsExit();
    helper->SDL_Exit();
    delete(helper);

Testing the homebrew:

YuZu now supports SDL Rendering in latest Canary:

https://github.com/yuzu-emu/yuzu-canary/releases

For testing in Real-Hardware we have two options:

- Copy the generated .nro to the SD/switch folder and test it from the HBMenu.
- Use NX Link:

NXLink is already installed with devkitpro if Switch tools are installed. If you don't have it, install switch tools with pacman.

- Go to the HBMenu in your switch and press Y to start the netloader. A pop-up will appear with the IP of your switch (It must be connected to Internet).

(You can do the commands directly in Windows CMD, but this is more comfy)

- Go back to your computer and create a text file with this commands:

cd path\to\devkitPro\tools\bin
nxlink -s -a 192.xxx.xxx.xxx path\to\homebrew.nro

Where the numbers are the IP shown in your switch's screen

Save the text file with .bat extension.

Just double click on the bat and it will start sending the HB to your switch. After the copy, the homebrew will run automatically.

Template:

In the template you will find a good example of how to create a game easily with template classes: Splash Screen, Title Screen, Intro Screen (cinematic) and Game Screen.

It has some UI classes for creating sprites, buttons and toggles. Sprites can be animated by frames. Sprites can be draggable with the Switch touch screen.

It has game data and multilanguage support with JSON.

Take a look to it, and if you need help, just ask.

Credits:

Spoiler

SDL2 references:

• joel16
• bernardo giordano
• Cheeze

Help and simple tutorial:

• Cid2mizard
• WerWolv

General:

• Credits for everyone involved in LibNX and Homebrew Development
• Thanks, SciresM for your awesome work in Atmosphere CFW.
• Smealum, because you deserve it, dude.

If this tutorial has been useful to you, credits are appreaciated.
For anything, just leave a comment below.

 

[eyeliner]

If you have everything correctly setup you maybe are not including the needed headers: sdl.h and sdl_image.h.

This should be it.
I didn't include them.

 

[eyeliner]

It seems you didn’t install SDL correctly by pacman (adding packages section). Check with -Syuu which ones you have and which ones you don’t

If you have everything correctly setup you maybe are not including the needed headers: sdl.h and sdl_image.h.

If you have the libraries installed, you should be able to compile any of my homebrews by yourself.

Bah, now it rants that it can't find SDL.h and SDL_image.h in the #includes.
I downloaded SDL2 and SDL_image sources and slapped them in the include folder of devkitPro.
I have serious difficulties wrapping my head around c/c++ configuration.

This thing can be simple, but it really is not...

 

[Manurocker95]

This should be it.
I didn't include them.

If you want to use my helper, it includes everything by default. Just include sdlHelper.h

Bah, now it rants that it can't find SDL.h and SDL_image.h in the #includes.
I downloaded SDL2 and SDL_image sources and slapped them in the include folder of devkitPro.
I have serious difficulties wrapping my head around c/c++ configuration.

This thing can be simple, but it really is not...

Use pacman instead. You just need to use pacman -Syuu packagename and to know the packages' name pacman -Sl

--------------------- MERGED ---------------------------

Bah, now it rants that it can't find SDL.h and SDL_image.h in the #includes.
I downloaded SDL2 and SDL_image sources and slapped them in the include folder of devkitPro.
I have serious difficulties wrapping my head around c/c++ configuration.

This thing can be simple, but it really is not...

When doing pacman -Sl be sure you have them installed

 

[eyeliner]

If you want to use my helper, it includes everything by default. Just include sdlHelper.h

Use pacman instead. You just need to use pacman -Syuu packagename and to know the packages' name pacman -Sl

When doing pacman -Sl be sure you have them installed View attachment 159942

switch-sdl2 reports as installed.
I'm using your helper: #include "sdl_helper.hpp"

SDL_Texture * myTexture is always marked as undefined. I have no idea what is wrong, really, I don't.

Do I have to get ALL your files in my source folder? Or only those 4 you specifically mentioned?

 

[Manurocker95]

switch-sdl2 reports as installed.
I'm using your helper: #include "sdl_helper.hpp"

SDL_Texture * myTexture is always marked as undefined. I have no idea what is wrong, really, I don't.

Do I have to get ALL your files in my source folder? Or only those 4 you specifically mentioned?

No, you need to have it linked in the makefile and your VS solution

 

[eyeliner]

No, you need to have it linked in the makefile and your VS solution

Then I have no idea of what I am doing.
Thanks for the patience.

 

[Manurocker95]

Then I have no idea of what I am doing.
Thanks for the patience.

Don't worry. Take my template and try to compile it using make. If you can compile it that way, download the solution, open it and use it as base if you want

 

[JupiterJesus]

When installing sdl using the provided pacman command line, I had to replace "switch-sdl" with "switch-sdl2" to get it to work. switch-sdl just gives an error, no such library found.

I also had to add "path\to\devkitPro\portlibs\switch\include" to my vc++ directories include list. I guess that's where sdl2 got installed.

Finally, I couldn't just include <SDL.h>. I had to include <SDL2\SDL.h>, since the SDL includes were in "path\to\devkitPro\portlibs\switch\include\SDL2". Similarly, #include <SDL2\SDL_Image.h>.

I also needed more than the 4 files listed from the template github project, since other files are #included from the ones we use. These were Settings.hpp and Colors.h.

Finally for real this time, I had to remove -lavformat -lavcodec -lswresample -lswscale -lavutil -lbz2 -lass -ltheora -lvorbis -lopus from the LIBS definition in the makefile. Maybe these are libs that are required by some of the SDL2 libs, but the tutorial didn't give instructions to install them and the obvious thing (calling pacman to install the missing libs) didn't work, at least not with the obvious names e.g. avformat, avcodec, etc.

At this point the Makefile compiles. The only thing left is that I get intellisense errors when including stdio.h, stdlib.h, string.h and other C std libraries. I don't know why - seems like these of all things should be a simple thing for VS to find.

 

[urherenow]

Why? Why do this? Use devkit like it was intended to be, and use pacman/dkp-pacman to keep the libraries up to date. Using different setups will create different bugs and end up being a headache for devs. People are likely to end up using the wrong gcc, and wrong "standard" libraries. Devkit installers/scripts are available for all systems. If you're not using ubuntu bash on windows subsystem, the proper thing to use is msys2 (included when you simply install devkitpro with the installer).

 

[Manurocker95]

When installing sdl using the provided pacman command line, I had to replace "switch-sdl" with "switch-sdl2" to get it to work. switch-sdl just gives an error, no such library found.

I also had to add "path\to\devkitPro\portlibs\switch\include" to my vc++ directories include list. I guess that's where sdl2 got installed.

Finally, I couldn't just include <SDL.h>. I had to include <SDL2\SDL.h>, since the SDL includes were in "path\to\devkitPro\portlibs\switch\include\SDL2". Similarly, #include <SDL2\SDL_Image.h>.

I also needed more than the 4 files listed from the template github project, since other files are #included from the ones we use. These were Settings.hpp and Colors.h.

Finally for real this time, I had to remove -lavformat -lavcodec -lswresample -lswscale -lavutil -lbz2 -lass -ltheora -lvorbis -lopus from the LIBS definition in the makefile. Maybe these are libs that are required by some of the SDL2 libs, but the tutorial didn't give instructions to install them and the obvious thing (calling pacman to install the missing libs) didn't work, at least not with the obvious names e.g. avformat, avcodec, etc.

At this point the Makefile compiles. The only thing left is that I get intellisense errors when including stdio.h, stdlib.h, string.h and other C std libraries. I don't know why - seems like these of all things should be a simple thing for VS to find.

Using pacman -Sl you can see the names of the libraries. You just need to install the ones you wanna use. In my template I use the ones you see here. If you cant include sdl you maybe didn’t link the includes correctly or didn’t install the libs correctly.

--------------------- MERGED ---------------------------

Why? Why do this? Use devkit like it was intended to be, and use pacman/dkp-pacman to keep the libraries up to date. Using different setups will create different bugs and end up being a headache for devs. People are likely to end up using the wrong gcc, and wrong "standard" libraries. Devkit installers/scripts are available for all systems. If you're not using ubuntu bash on windows subsystem, the proper thing to use is msys2 (included when you simply install devkitpro with the installer).

I use VS because it is A LOT easier to develop stuff on windows if you are used to it. If you don’t want to use it, don’t do it. It works flawlessly for me.

 

[Zorn_Taov]

Ignore the errors in the Error List by turning it off or clicking "X of X Errors" once, where X is any given number.

is this because you haven't figured out the 435 errors starting with "cannot open source file "errno.h"" in the Error List? I made sure to include the portslib\switch\include folder and installing "Windows 8.1 SDK" though I couldn't find "UCRT SDK". I can compile just fine and the compiled .NRO works on my switch, but it'd be good to squash all errors, especially errors like these.

 

[Manurocker95]

is this because you haven't figured out the 435 errors starting with "cannot open source file "errno.h"" in the Error List? I made sure to include the portslib\switch\include folder and installing "Windows 8.1 SDK" though I couldn't find "UCRT SDK". I can compile just fine and the compiled .NRO works on my switch, but it'd be good to squash all errors, especially errors like these.

Are you using your own makefile? Are you running Windows 8.1 or Windows 10? Did you try opening an already created project?

 

[Zorn_Taov]

Are you using your own makefile? Are you running Windows 8.1 or Windows 10? Did you try opening an already created project?

started with the devkitpro/examples/switch/templates/application/makefile, changed it so the .nro/.nacp/.elf files end up in $(CURDIR)/Output/$(TARGET), then changed LIBS and LIBDIRS to

LIBS := -lpu -lfreetype -lSDL2_ttf -lSDL2_gfx -lSDL2_image -lSDL2 -lEGL -lGLESv2 -lglapi -ldrm_nouveau -lpng -ljpeg `sdl2-config --libs` `freetype-config --libs` -lnx
LIBDIRS := $(PORTLIBS) $(LIBNX) $(CURDIR)/Plutonium

so that I could use Plutonium for a menu system. I'm using Windows 10 and created a new project by the tutorial in the opening post you made.

 

[Manurocker95]

started with the devkitpro/examples/switch/templates/application/makefile, changed it so the .nro/.nacp/.elf files end up in $(CURDIR)/Output/$(TARGET), then changed LIBS and LIBDIRS to

LIBS := -lpu -lfreetype -lSDL2_ttf -lSDL2_gfx -lSDL2_image -lSDL2 -lEGL -lGLESv2 -lglapi -ldrm_nouveau -lpng -ljpeg `sdl2-config --libs` `freetype-config --libs` -lnx
LIBDIRS := $(PORTLIBS) $(LIBNX) $(CURDIR)/Plutonium

so that I could use Plutonium for a menu system. I'm using Windows 10 and created a new project by the tutorial in the opening post you made.

I got so many problemas with Plutonium but if you have everything installed, it should work without issues. Hmm, can you compile any of my hbs? I tested to open one of my solutions and it works fine

 

[Zorn_Taov]

I got so many problemas with Pl
utonium but if you have everything installed, it should work without issues. Hmm, can you compile any of my hbs? I tested to open one of my solutions and it works fine

well after installing everything starting with "switch-" in pacman, I got WhatsInTheBox to compile and run on the switch and it's the same situation. Almost all of these errors are actually errors in intellisense being unable to find those source files for some reason. Here's a CSV file of the errors when looking at the main.cpp of WhatsInTheBox. pastebin EdneqQ22 and just put that into a spreadsheet to read it easier

EDITED:
I eventually found "Windows Universal CRT SDK" which is the UCRT SDK listed above and I think that got rid of most of the errors(?) Though intellisense still can't find sys/lock.h and stdalign.h.

EDIT 2:
I've given up on using Plutonium. it's using C++17 only things and visual studio won't comply to my makefiles settings in that regard, thus adding to the warnings that don't actually break the compiler.

 

[wstlxx]

Hello Manurocker95, I am trying to set up the whole environment with visualstudio 2019 .The build was a huge success, thank you for the tutorial.
May i ask if there is a proper way to do some debug?
Is it gonna be tools like GDB?

 

[Manurocker95]

Hello Manurocker95, I am trying to set up the whole environment with visualstudio 2019 .The build was a huge success, thank you for the tutorial.
May i ask if there is a proper way to do some debug?
Is it gonna be tools like GDB?

For 3DS, Citra displays logs but YuZu AFAIK doesn't, so... :/

On real hardware, you can use nxlink to debug logs. I never got used to it so I used my own text rendering for debugging.

 

[wstlxx]

For 3DS, Citra displays logs but YuZu AFAIK doesn't, so... :/

On real hardware, you can use nxlink to debug logs. I never got used to it so I used my own text rendering for debugging.

I just found a tool named Twili. I haven't fully understand it yet ,but i think it will be of good use.

 

[Gigaboy]

So, I got this working and I was extremely happy there was no compilation errors and such. I compiled your just the main.cpp file you provided and it works first try (amazingly). But then VS said there was errors, so without changing any code I rebuild the solution and it doesn't compile now. So, I open my terminal and enter "make" and it gives me an error with a .elf file. Any suggestions?

collect2.exe: error: ld returned 1 exit status
make[1]: *** [/opt/devkitpro/libnx/switch_rules:80: /home/imado/source/repos/Switch-Sandbox/Switch-Sandbox.elf] Error 1
make: *** [Makefile:165: build] Error 2

EDIT:
Actually, I lied. I did modify the code. I added "using namespace std;" and remove all the "std::"s and changed "char* argv[]" to "char** argv". But that was before the first build when it still worked.

ANOTHER EDIT:
I got it to work myself. Turns out I typed one of the libraries wrong in the makefile where I modified LIB variable.

 

[mo_v]

$(ProjectDir)\include

I don't know what you mean by ProjectDir where do you find that.