library: docs: example: Refactor debug mode builds

Instead of asking the user to rebuild the library, now it is possible
to build the library in both release and debug modes and to have both
versions of the library compiled at the same time.

.gitignore

@@ -1,7 +1,8 @@
 # Compiled files
 build/
+build_debug/
+build_release/
 lib/
-*.o
 *.nds
 *.elf
 

Makefile

@@ -15,12 +15,18 @@ include $(DEVKITARM)/ds_rules
 # DATA is a list of directories containing data files
 # INCLUDES is a list of directories containing header files
 #---------------------------------------------------------------------------------
-TARGET		:=	NE
-BUILD		:=	build
 SOURCES		:=	source source/dsma
 DATA		:=	data
 INCLUDES	:=	include
 
+ifeq ($(NE_DEBUG),1)
+	TARGET	:=	NE_debug
+	BUILD	:=	build_debug
+else
+	TARGET	:=	NE
+	BUILD	:=	build_release
+endif
+
 #---------------------------------------------------------------------------------
 # options for code generation
 #---------------------------------------------------------------------------------
@@ -31,6 +37,10 @@ CFLAGS	:=	-g -Wall -O2\
 		-fomit-frame-pointer -ffast-math \
 		$(ARCH) -Wno-address-of-packed-member
 
+ifeq ($(NE_DEBUG),1)
+	CFLAGS	+= -DNE_DEBUG
+endif
+
 CFLAGS	+=	$(INCLUDE) -DARM9
 CXXFLAGS	:= $(CFLAGS) -fno-rtti -fno-exceptions
 
@@ -103,7 +113,7 @@ $(BUILD): lib
 #---------------------------------------------------------------------------------
 clean:
 	@echo clean ...
-	@rm -fr $(BUILD) lib
+	@rm -fr build_debug build_release lib
 
 #---------------------------------------------------------------------------------
 else

examples/other/error_handling/Makefile

@@ -44,6 +44,10 @@ ARCH := -marm -mthumb-interwork -march=armv5te -mtune=arm946e-s
 
 CFLAGS   := -g -Wall -O3\
             $(ARCH) $(INCLUDE) -DARM9
+
+# Enable debug mode of Nitro Engine
+CFLAGS   += -DNE_DEBUG
+
 CXXFLAGS := $(CFLAGS) -fno-rtti -fno-exceptions
 ASFLAGS  := -g $(ARCH)
 LDFLAGS   = -specs=ds_arm9.specs -g $(ARCH) -Wl,-Map,$(notdir $*.map)
@@ -51,7 +55,8 @@ LDFLAGS   = -specs=ds_arm9.specs -g $(ARCH) -Wl,-Map,$(notdir $*.map)
 #---------------------------------------------------------------------------------
 # any extra libraries we wish to link with the project (order is important)
 #---------------------------------------------------------------------------------
-LIBS := -lNE -lfat -lnds9
+# Use debug version of Nitro Engine
+LIBS := -lNE_debug -lfat -lnds9
 
 # automatigically add libraries for NitroFS
 ifneq ($(strip $(NITRO)),)

include/NEGeneral.h

@@ -19,6 +19,12 @@
 /// General functions to control Nitro Engine, setup screens, print debug
 /// messages, etc.
 ///
+/// If Nitro Engine is compiled with debug features, it will check a lot of
+/// things and it will print error messages to an user-defined function. Check
+/// the error handling example for more details. If you have finished testing
+/// your code, just comment the define out and recompile Nitro Engine to save
+/// RAM and CPU usage.
+///
 /// @{
 
 /// Void function pointer used in NE_Process and NE_ProcessDual.
@@ -287,11 +293,30 @@ void NE_DebugSetHandlerConsole(void);
 
 #else // #ifndef NE_DEBUG
 
-#define NE_AssertMinMax(min, value, max, format...)
+#define NE_AssertMinMax(min, value, max, format...) \
-#define NE_AssertPointer(ptr, format...)
+    do {                                            \
-#define NE_Assert(cond, format...)
+        (void)(min);                                \
+        (void)(value);                              \
+        (void)(max);                                \
+    } while (0);
+
+#define NE_AssertPointer(ptr, format...)            \
+    do {                                            \
+        (void)(ptr);                                \
+    } while (0);
+
+#define NE_Assert(cond, format...)                  \
+    do {                                            \
+        (void)(cond);                               \
+    } while (0);
+
 #define NE_DebugPrint(format...)
-#define NE_DebugSetHandler(fn)
+
+#define NE_DebugSetHandler(fn)                      \
+    do {                                            \
+        (void)(fn);                                 \
+    } while (0);
+
 #define NE_DebugSetHandlerConsole()
 
 #endif

include/NEMain.h

@@ -25,15 +25,6 @@
 extern "C" {
 #endif
 
-/// Enable debug features.
-///
-/// If Nitro Engine is compiled with this option, it will check a lot of things
-/// and it will print error messages to an user-defined function. Check the
-/// error handling example for more details. If you have finished testing your
-/// code, just comment the define out and recompile Nitro Engine to save RAM and
-/// CPU usage.
-#define NE_DEBUG
-
 #include "NE2D.h"
 #include "NEAnimation.h"
 #include "NECamera.h"

readme.rst

@@ -28,10 +28,20 @@ Setup
 
 1. Clone this repository. Create a symbolic link) to it inside the devkitPro
    folder in your system. For example, in Linux, create a symlink so that
-   ``/opt/devkitpro/nitro-engine`` points to the folder with Nitro Engine.
+   ``/opt/devkitpro/nitro-engine`` points to the folder with Nitro Engine:
 
-2. Go to the cloned repository type ``make`` on the terminal. This should build
+   .. code:: bash
-   the library.
+
+       ln -sT /path/to/nitro-engine /opt/devkitpro/nitro-engine
+
+2. Go to the ``nitro-engine`` folder and type this on the terminal:
+
+   .. code:: bash
+
+       make
+       make NE_DEBUG=1
+
+   This should build the library in both debug and release modes.
 
 3. If you want to check that everything is working as expected, open one of the
    folders of the examples and type ``make``. That should build an ``.nds`` file
@@ -41,10 +51,12 @@ Setup
    correctly. **DeSmuME** doesn't emulate the polygon/vertices count registers,
    so the touch test feature of Nitro Engine doesn't work.
 
-4. By default, Nitro Engine is compiled with debug options enabled. Go to
+4. Normally you should link your programs with ``-lNE``, which is the release
-   ``NEMain.h`` and comment the line ``#define NE_DEBUG`` to disable them and
+   version of Nitro Engine. If you want to use the debug features of Nitro
-   save CPU usage and memory. You'll need to recompile the library for the new
+   Engine, you should link with ``-lNE_debug``, and add ``-DNE_DEBUG`` to the
-   value to take effect.
+   ``CFLAGS`` and ``CPPFLAGS`` in your Makefile. Make sure to clean and rebuild
+   your project after doing the changes mentioned in this step. Check the
+   **error_handling** function to see how to use the debug mode of Nitro Engine.
 
 Screenshots
 -----------