documentation: getting started with wonderful toolchain guide

butano/include/bn_game_pak_wait_state.h

@@ -40,7 +40,7 @@
  *
  * Game Pak access time is 2+1 clock cycles for non-sequential accesses.
  *
- * This setting is not supported by the Nintendo 3DS nor slow flash carts like the SuperCard SD.
+ * This setting is not supported by the Nintendo 3DS or slow flash carts like the SuperCard SD.
  *
  * @ingroup game_pak
  */

butano/include/documentation/bn_documentation_a_getting_started.h → butano/include/documentation/bn_documentation_aa_getting_started.h

@@ -13,11 +13,16 @@
  *
  * @tableofcontents
  *
+ *
  * @section getting_started_supported_platforms Supported platforms
  *
  * Butano is built on top of the <a href="https://devkitpro.org/">devkitARM</a> toolchain,
  * so it supports Windows, macOS and Unix-like platforms.
  *
+ * There's also experimental support for <a href="https://wonderful.asie.pl/">Wonderful Toolchain</a>.
+ * If you want to try it, go to @ref getting_started_wt.
+ *
+ *
  * @section getting_started_emulator GBA emulator
  *
  * Before anything, it is convenient to have a GBA emulator at hand,
@@ -37,7 +42,7 @@
  * * Make sure that **with the system console (not with the MSYS2 one)** you are able to build and run
  *   some of the examples located in `/path/to/devkitpro/examples/gba`:
  *   * By default, devkitARM is installed in `C:\devkitPro\` on Windows and in `/opt/devkitpro/` on Ubuntu.
- *   * To build a devkitARM example open the system console, `cd` to the folder of the example you want to build
+ *   * To build a devkitARM example, open the system console, `cd` to the folder of the example you want to build
  *     and type `make -j8` if your CPU has 8 cores, `make -j16` if it has 16 and so on.
  *   * In particular, you should build and run the Maxmod example located in
  *     `/path/to/devkitpro/examples/gba/audio/maxmod` before going on.
@@ -55,7 +60,7 @@
  * you are going to need <a href="https://www.python.org/">Python</a>.
  *
  * If you are going to install Python on Windows,
- * remember to add it to the PATH and to close all system console windows before installing it:
+ * remember to add it to the `PATH` and to close all system console windows before installing it:
  *
  * @image html python_windows.png
  *
@@ -74,7 +79,7 @@
  * @section getting_started_butano Butano
  *
  * Download or clone the latest Butano release from <a href="https://github.com/GValiente/butano">GitHub</a>
- * and put it in a path without spaces or anything weird like that, please.
+ * and put it in a path without spaces or anything weird, please.
  *
  *
  * @section getting_started_examples Butano examples
@@ -83,7 +88,7 @@
  *
  * Make sure that you are able to build and run some of them:
  * * They are located in `/path/to/butano/examples/`.
- * * As with <a href="https://devkitpro.org/">devkitARM</a> examples, to build a Butano example
+ * * As with <a href="https://devkitpro.org/">devkitARM</a> examples, to build a Butano example,
  *   open the system console (not the MSYS2 one), `cd` to the folder of the example you want to build
  *   and type `make -j8` if your CPU has 8 cores, `make -j16` if it has 16 and so on.
  *
@@ -100,7 +105,7 @@
  *
  * If you were able to build and run some examples, congrats! Now you can make your own GBA game with Butano.
  * To do that:
- * * Copy the template project located in `/path/to/butano/template/` to a path without spaces nor weird characters.
+ * * Copy the template project located in `/path/to/butano/template/` to a path without spaces or weird characters.
  * * Change in the `Makefile` the path in which Butano library folder is located.
  *   For example, if Butano is located in `/path/to/butano/`,
  *   `LIBBUTANO` variable should be set to `/path/to/butano/butano`.

butano/include/documentation/bn_documentation_ab_getting_started_wt.h

@@ -0,0 +1,121 @@
+/*
+ * Copyright (c) 2020-2023 Gustavo Valiente [email protected]
+ * zlib License, see LICENSE file.
+ */
+
+#ifndef BN_DOCUMENTATION_GETTING_STARTED_WT_H
+#define BN_DOCUMENTATION_GETTING_STARTED_WT_H
+
+/**
+ * @page getting_started_wt Getting started with Wonderful Toolchain
+ *
+ * Downloading Butano and building their games and examples is easy and doesn't take too much time, pinky promise.
+ *
+ * @tableofcontents
+ *
+ *
+ * @section getting_started_wt_supported_platforms Supported platforms
+ *
+ * <a href="https://wonderful.asie.pl/">Wonderful Toolchain</a> supports Windows and Unix-like platforms.
+ *
+ * If you want to develop on macOS, you should try to use a Linux virtual machine or
+ * @ref getting_started "devkitARM" instead.
+ *
+ *
+ * @section getting_started_wt_emulator GBA emulator
+ *
+ * Before anything, it is convenient to have a GBA emulator at hand,
+ * so you don't have to test in real hardware each change you make in your project.
+ *
+ * For developing GBA games, <a href="https://mgba.io">mGBA</a>,
+ * <a href="https://github.com/nba-emu/NanoBoyAdvance">NanoBoyAdvance</a> and the debug version of
+ * <a href="https://problemkaputt.de/gba.htm">No$gba</a> are recommended.
+ *
+ *
+ * @section getting_started_wt_wt Wonderful Toolchain
+ *
+ * The next step is to download and install <a href="https://wonderful.asie.pl/">Wonderful Toolchain</a>
+ * using <a href="https://wonderful.asie.pl/docs/getting-started/">this tutorial</a>.
+ *
+ * From now on, this guide assumes a Windows environment, but the steps to take for Unix-like platforms
+ * should be similar.
+ *
+ * @image html wt_installer.png
+ *
+ * Once installed, open the Wonderful Toolchain Shell and run the following commands,
+ * accepting the default options when prompted:
+ *
+ * @code{.cpp}
+ * pacman -S make
+ * wf-pacman -Syu
+ * wf-pacman -S toolchain-gcc-arm-none-eabi
+ * wf-pacman -S thirdparty-blocksds-toolchain
+ * wf-pacman -S target-gba
+ * @endcode
+ *
+ * @image html wt_pacman.png
+ *
+ *
+ * @section getting_started_wt_python Python
+ *
+ * To execute some of the tools needed to include image and audio files in your project,
+ * you are going to need <a href="https://www.python.org/">Python</a>.
+ *
+ * If you are going to install Python on Windows,
+ * remember to add it to the `PATH` and to close all system console windows before installing it:
+ *
+ * @image html python_windows.png
+ *
+ * Both Python 2 and Python 3 are supported for now, but Python 2 is not going to be supported for too long.
+ * Make sure you can execute Python from the Wonderful Toolchain Shell:
+ *
+ * @image html wt_python.png
+ *
+ * If you have an Ubuntu/Debian based system with `python3` instead of `python`, you can:
+ * * Specify `python3` as the Python interpreter path in the `Makefile` of the project you are trying to build.
+ * * Install `python-is-python3`: `sudo apt-get install python-is-python3`.
+ *
+ *
+ * @section getting_started_wt_butano Butano
+ *
+ * Download or clone the latest Butano release from <a href="https://github.com/GValiente/butano">GitHub</a>
+ * and put it in a path without spaces or anything weird, please.
+ *
+ *
+ * @section getting_started_wt_examples Butano examples
+ *
+ * Butano contains multiple @ref examples "examples" of most aspects of the engine.
+ *
+ * Make sure that you are able to build and run some of them:
+ * * They are located in `/path/to/butano/examples/`.
+ * * To build a Butano example, open the Wonderful Toolchain Shell, `cd` to the folder of the example
+ *   you want to build and type `make -j8` if your CPU has 8 cores, `make -j16` if it has 16 and so on.
+ *
+ * @image html wt_example_1.png
+ *
+ * When trying to build the `sprites` example, if everything went as expected,
+ * a `sprites.gba` file should have been generated in the `sprites` folder,
+ * and the system console should show something like this:
+ *
+ * @image html wt_example_2.png
+ *
+ *
+ * @section getting_started_wt_template Make your own GBA game!
+ *
+ * If you were able to build and run some examples, congrats! Now you can make your own GBA game with Butano.
+ * To do that:
+ * * Copy the template project located in `/path/to/butano/template/` to a path without spaces or weird characters.
+ * * Change in the `Makefile` the path in which Butano library folder is located.
+ *   For example, if Butano is located in `/path/to/butano/`,
+ *   `LIBBUTANO` variable should be set to `/path/to/butano/butano`.
+ * * If you want, you can also change ROM title, ROM code and more in the `Makefile`.
+ * * `cd` to the new folder.
+ * * Type `make -j#cpu_cores#` again.
+ *
+ * If everything went as expected, a `*.gba` file should have been generated in the project folder!
+ * Now learn how to @ref import "import your assets" in the game and
+ * also take a look at the <a href="modules.html">modules</a> page.
+ * The @ref faq "frequently asked questions (FAQ)" are worth a look too.
+ */
+
+#endif

butano/include/documentation/bn_documentation_c_import.h

@@ -34,7 +34,7 @@
  * Butano for now is a little finicky about the images it likes, sorry.
  *
  * The required image format is the following:
- * * BMP without compression nor color space information.
+ * * BMP without compression or color space information.
  * * 16 or 256 colors only.
  * * The first color in the color palette is the transparent one, so in most cases it will not be shown on screen.
  *

butano/include/documentation/bn_documentation_e_faq.h

@@ -356,7 +356,7 @@
  * @subsection faq_sprites_utf8_characters How can I print UTF-8 characters like japanese or chinese ones?
  *
  * bn::sprite_text_generator already supports UTF-8 characters rendering,
- * but the bn::sprite_font instances used in the examples don't provide japanese nor chinese characters,
+ * but the bn::sprite_font instances used in the examples don't provide japanese or chinese characters,
  * so you will have to make a new one with them.
  *
  *

butano/include/documentation/bn_documentation_f_changelog.h

@@ -14,6 +14,8 @@
  *
  * @section changelog_16_4_0 16.4.0 (next release)
  *
+ * * <a href="https://wonderful.asie.pl/">Wonderful Toolchain</a> experimental support!
+ *   See the @ref getting_started_wt guide to learn how to build Butano games with it.
  * * Real time clock (RTC) support thanks to <a href="https://github.com/felixjones/agbabi">agbabi</a>.
  *   See bn::date, bn::time and the `date_time` example to learn how to deal with the RTC.
  * * bn::core::hard_reset added.
@@ -500,7 +502,7 @@
  * @section changelog_10_3_0 10.3.0
  *
  * * bn::bg_tiles::allow_offset and bn::bg_tiles::set_allow_offset added.
- * * Import tool now can generate regular and affine background tiles without maps nor palettes.
+ * * Import tool can now generate regular and affine background tiles without maps or palettes.
  *   See the @ref import_regular_bg_tiles and the @ref import_affine_bg_tiles import guides to learn how to import them.
  * * BPP mode can be specified when importing sprite tiles.
  *   See the @ref import_sprite_tiles import guide to learn how to specify it.
@@ -790,7 +792,7 @@
  *
  * @section changelog_7_3_0 7.3.0
  *
- * * bn::sprite_text_generator now can plot multiple 16x16 variable width characters in a single sprite.
+ * * bn::sprite_text_generator can now plot multiple 16x16 variable width characters in a single sprite.
  * * bn::sprite_text_generator IWRAM usage reduced.
  * * Third party libraries to link can be specified in the project's `Makefile`.
  * * Project's `Makefile` allows to build source files generated with an external tool.
@@ -1094,7 +1096,7 @@
  *
  * @section changelog_4_2_0 4.2.0
  *
- * * Sprite and background palettes can be generated from images alone, without tiles nor maps.
+ * * Sprite and background palettes can be generated from images alone, without tiles or maps.
  * * `<cstddef>` is always included (`bn_cstddef.h` header file removed).
  * * bn::unordered_map and bn::unordered_set assignment fixed.
  *