Tests: Added test project + Added README for tests

Signed-off-by: Patrick Pedersen <ctx.xda@gmail.com>

Dockerfile

@@ -20,5 +20,7 @@ RUN for version in 3.8.0 3.9.0 4.0.0 4.1.0 4.2.0 4.3.0 4.4.0; do \
 
 COPY . /root/
 
+RUN pip3 install /root/ --break-system-packages
+
 # Set the entrypoint to /bin/bash
-ENTRYPOINT ["/usr/bin/bash", "/root/test.sh"]
+ENTRYPOINT ["/usr/bin/bash", "/root/test/test.sh", "--ACK"]

test/README.md

@@ -0,0 +1,47 @@
+# Tests
+
+This directory contains tests for the stm8dce tool, divided into two main parts:
+
+1. **test.py**: Contains unit tests to verify the functionality of the stm8dce tool. These tests use a set of tailored C files (`main.c`, `_main.c`, `extra.c`) to rigorously check various features and ensure the tool behaves as expected. The unit tests validate the returned lists of excluded and kept functions and constants against predefined expected outputs.
+
+2. **test_project**: A test project designed to evaluate the stm8dce tool's performance on a real project. This project is based on the ["Dampflog Interface Board Firmware"](https://github.com/TuDo-Makerspace/Dampflog). It aims to identify potential issues that might not be covered by the unit tests. The test project is only tested for successful compilation.
+
+These tests are ran accross multiple SDCC version to ensure broader compatibility. Currently, the tests are run on the following SDCC versions:
+
+- 3.8.0
+- 3.9.0
+- 4.0.0
+- 4.1.0
+- 4.2.0
+- 4.3.0
+- 4.4.0
+
+Older versions than 3.8.0 are not tested since these are not available as precompiled binaries on the official SDCC website.
+
+## Running the tests
+
+### Full test
+
+The full test is intended to be run in a Docker container. The root directory of the stm8dce repository provides a Dockerfile that runs the tests on all supported SDCC versions. To build the Docker image, run the following command:
+
+```bash
+docker build -t stm8dce-test .
+```
+
+To run the tests, execute the following command:
+
+```bash
+docker run stm8dce-test
+```
+
+The Docker container will run the tests on all supported SDCC versions and output the results to the console.
+
+It is not recommended to run the full test without docker, as it will clutter your system with multiple SDCC versions and other test-relevant dependencies.
+
+### Unit test only
+
+For faster testing, it's recommended to run the unit tests for your installed SDCC version only. To do so, simply run the `test.py` script:
+
+```bash
+python3 test.py
+```

test.sh → test/test.sh

@@ -15,13 +15,26 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-# Description: This script runs the unit tests for each SDCC version specified in the SDCC_VERSIONS array.
+# Description: This script runs unit tests and builds a test project for each version of SDCC listed in the SDCC_VERSIONS array.
 
 # NOTE: This script is launched by the dockerfile of the project. Since this script relies on the SDCC binaries
 #       being installed in the /opt directory, it is recommended to run this script as intended by the dockerfile.
 #       To do so, simply run the following command:
 #       docker build -t stm8dce-test . && docker run stm8dce-test 
 
+if [ "$1" != "--ACK" ]; then
+    echo "WARNING: This test script is intended to be run by the dockerfile of the project."
+    echo
+    echo "From the root of this repo, please run:"
+    echo "  docker build -t stm8dce-test . && docker run stm8dce-test"
+    echo
+    echo "The dockerfile pulls all necessary dependencies and avoids cluttering your system with multiple SDCC binaries and other dependencies."
+    echo
+    echo "If you still insist on running this script on your host system, please provide the --ACK flag to acknowledge this warning."
+    exit 1
+fi
+
+
 SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
 
 # Tested SDCC versions (These are available as pre-built binaries)
@@ -33,17 +46,39 @@ FAILED_VERSIONS=()
 # Escape codes for colored output
 GREEN='\033[0;32m'
 RED='\033[0;31m'
+BOLD='\033[1m'
 NC='\033[0m' # No Color
 
 # Run unit tests for each SDCC version
 for version in "${SDCC_VERSIONS[@]}"; do
+    echo
+    echo "============================================================ SDCC version $version ============================================================"
     export PATH="/opt/sdcc-$version/bin:$PATH"
 
-    echo "Running test.py with SDCC version $version"
-    if python3 $SCRIPT_DIR/test/test.py $SCRIPT_DIR/test/build-$version; then
-        PASSED_VERSIONS+=("$version")
+    echo
+    echo -e "${BOLD}Running unit tests:${NC}"
+    python3 $SCRIPT_DIR/test.py $SCRIPT_DIR/build-$version
+    UNITTEST_RET=$?
+
+    echo
+    echo -e "${BOLD}Building test project:${NC}"
+    cd $SCRIPT_DIR/test_project
+    make clean BUILD_DIR=$SCRIPT_DIR/build-$version
+    make BUILD_DIR=$SCRIPT_DIR/build-$version
+
+    EXAMPLE_RET=$?
+    if [ $EXAMPLE_RET -ne 0 ]; then
+        echo -e "${RED}Failed to build test project with SDCC version $version${NC}"
+    else
+        echo -e "${GREEN}Successfully built test project with SDCC version $version${NC}"
+    fi
+
+    cd $SCRIPT_DIR
+
+    if [ $UNITTEST_RET -eq 0 ] && [ $EXAMPLE_RET -eq 0 ]; then
+        PASSED_VERSIONS+=($version)
     else
-        FAILED_VERSIONS+=("$version")
+        FAILED_VERSIONS+=($version)
     fi
 done
 

test/test_project/Makefile

@@ -0,0 +1,156 @@
+ifndef BUILD_DIR
+$(error BUILD_DIR is not set)
+endif
+
+#######################################
+# Toolchain
+#######################################
+
+CC = sdcc
+LD = sdcc
+AS = sdasstm8
+DCE = stm8dce
+
+MKDIR = mkdir
+CP = cp
+
+# Find the standard library path dynamically
+STDLIB_PATH := $(shell dirname $(shell which sdcc))/../share/sdcc/lib/stm8/stm8.lib
+
+#######################################
+# Build options
+#######################################
+
+# MCU Variant
+DEFINE = -DSTM8S103 # Change to your STM8S variant
+
+# Defines
+DEFINE +=
+
+# Include directories
+INCLUDE = $(addprefix -I, \
+	include/ \
+	src/ \
+)
+
+# Compiler flags
+CC_FLAGS = -mstm8 --out-fmt-elf
+
+# Project name
+PROJECT = blinky
+
+# Assembly files
+ASM_DIR = $(BUILD_DIR)/asm
+AS_FLAGS = -plosg -ff
+
+# Dead Code Elimination
+DCE_DIR = $(BUILD_DIR)/dce
+DCE_FLAGS =
+
+# Object files
+OBJ_DIR = $(BUILD_DIR)/obj
+
+# Source files
+VPATH += src
+SRC_FILES = $(wildcard src/*.c) # Compile all .c files in src directory
+
+# Libraries
+LIBS = $(STDLIB_PATH)
+
+# Linker flags
+LD_FLAGS = -mstm8 --out-fmt-elf --opt-code-size
+
+# Size Check
+RAM_SIZE = 1024
+FLASH_SIZE = 8192
+
+#######################################
+# Flash Options
+#######################################
+
+FLASH_FLAGS = -c stlinkv2 -p stm8s103f3
+
+#######################################
+# Standard Peripheral Library
+#######################################
+
+VPATH += lib/STM8S_StdPeriph_Driver/src
+INCLUDE += -Ilib/STM8S_StdPeriph_Driver/inc
+
+# Comment/Uncomment according to your STM8S variant
+# Which peripherals apply to your STM8S variant can be found out
+# by looking at the STM8S_StdPeriph_Driver/inc/stm8s.h file
+
+STDPER_SRC 	+= stm8s_adc1.c
+# STDPER_SRC 	+= stm8s_adc2.c
+STDPER_SRC 	+= stm8s_awu.c
+STDPER_SRC 	+= stm8s_beep.c
+# STDPER_SRC 	+= stm8s_can.c
+STDPER_SRC 	+= stm8s_clk.c
+STDPER_SRC 	+= stm8s_exti.c
+STDPER_SRC 	+= stm8s_flash.c
+STDPER_SRC 	+= stm8s_gpio.c
+STDPER_SRC 	+= stm8s_i2c.c
+STDPER_SRC 	+= stm8s_itc.c
+STDPER_SRC 	+= stm8s_iwdg.c
+STDPER_SRC 	+= stm8s_rst.c
+STDPER_SRC 	+= stm8s_spi.c
+STDPER_SRC 	+= stm8s_tim1.c
+STDPER_SRC 	+= stm8s_tim2.c
+# STDPER_SRC 	+= stm8s_tim3.c
+# STDPER_SRC 	+= stm8s_tim4.c
+# STDPER_SRC 	+= stm8s_tim5.c
+# STDPER_SRC 	+= stm8s_tim6.c
+STDPER_SRC 	+= stm8s_uart1.c
+# STDPER_SRC 	+= stm8s_uart2.c
+# STDPER_SRC 	+= stm8s_uart3.c
+# STDPER_SRC 	+= stm8s_uart4.c
+STDPER_SRC 	+= stm8s_wwdg.c
+
+SRC_FILES += $(STDPER_SRC)
+
+#######################################
+# MIDI RX Library
+#######################################
+
+VPATH += lib/midirx/src
+INCLUDE += -Ilib/midirx/include
+INCLUDE += -Ilib/midirx/src
+
+SRC_FILES += $(wildcard lib/midirx/src/*.c)
+
+#######################################
+# Project targets
+#######################################
+
+ASM = $(addprefix $(ASM_DIR)/, $(notdir $(SRC_FILES:.c=.asm)))
+DCE_ASM = $(addprefix $(DCE_DIR)/, $(notdir $(ASM:.asm=.asm)))
+OBJ = $(addprefix $(OBJ_DIR)/, $(notdir $(ASM:.asm=.rel)))
+
+all: $(BUILD_DIR)/$(PROJECT).elf
+
+elf: $(BUILD_DIR)/$(PROJECT).elf
+obj: $(OBJ)
+asm: $(ASM)
+dce: $(DCE_ASM)
+
+# ELF file
+$(BUILD_DIR)/$(PROJECT).elf: $(OBJ)
+	@$(MKDIR) -p $(BUILD_DIR)
+	$(LD) $(LD_FLAGS) -o $@ $(LIBS) $^
+
+$(ASM_DIR)/%.asm: %.c
+	@$(MKDIR) -p $(ASM_DIR)
+	$(CC) $< $(CC_FLAGS) $(INCLUDE) $(DEFINE) -S -o $@
+
+$(DCE_DIR)/%.asm: $(ASM)
+	@$(MKDIR) -p $(DCE_DIR)
+	$(DCE) $(DCE_FLAGS) -o $(DCE_DIR) $(LIBS) $^
+
+$(OBJ_DIR)/%.rel: $(DCE_DIR)/%.asm
+	@$(MKDIR) -p $(OBJ_DIR)
+	$(AS) $(AS_FLAGS) -o $@ $<
+
+# Clean
+clean:
+	rm -rf $(ASM_DIR)/ $(DCE_DIR) $(BUILD_DIR)/

test/test_project/README.md

@@ -0,0 +1,3 @@
+# Test Project
+
+This project is used to test if the stm8dce tool works on a real project. It is based on the ["Dampflog Interface Board Firmware"](https://github.com/TuDo-Makerspace/Dampflog) with slight modifications to make it compatible with older SDCC versions. The firmware acts as a decent benchmark, as it makes use of the SPL, contains function pointers and all around provides a somewhat richer codebase than a simple blinky example.

test/test_project/include/log.h

@@ -0,0 +1,43 @@
+/*
+ * Copyright (C) 2023 Patrick Pedersen, TU-DO Makerspace
+
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ * Description: Provides macros for logging over UART.
+ *
+ */
+
+#ifndef _LOG_H_INCLUDED
+#define _LOG_H_INCLUDED
+
+#include <stdio.h>
+
+/**
+ * @brief Logs a message to UART
+ * Logs a message to UART, including the file, line and function name.
+ * @param ... Message to log, including format specifiers (i.e like printf()).
+ */
+#define LOG(...)                                             \
+	printf("%s:%d, %s: ", __FILE__, __LINE__, __func__); \
+	printf(__VA_ARGS__);                                 \
+	printf("\n");
+
+// Same as LOG(), but not built if DEBUG is not defined.
+#ifdef DEBUG
+#define LOG_DEBUG(...) LOG(__VA_ARGS__)
+#else
+#define LOG_DEBUG(...)
+#endif
+
+#endif // _LOG_H_INCLUDED