Improve the example documentation and code

This commit is contained in:
Maschell 2023-02-25 20:51:48 +01:00
parent e40d91fcec
commit 54b09fe44c
7 changed files with 251 additions and 56 deletions

View File

@ -0,0 +1,67 @@
# Generated from CLion C/C++ Code Style settings
BasedOnStyle: LLVM
AccessModifierOffset: -4
AlignAfterOpenBracket: Align
AlignConsecutiveAssignments: Consecutive
AlignConsecutiveMacros: AcrossEmptyLinesAndComments
AlignOperands: Align
AllowAllArgumentsOnNextLine: false
AllowAllConstructorInitializersOnNextLine: false
AllowAllParametersOfDeclarationOnNextLine: false
AllowShortBlocksOnASingleLine: Always
AllowShortCaseLabelsOnASingleLine: false
AllowShortFunctionsOnASingleLine: All
AllowShortIfStatementsOnASingleLine: Always
AllowShortLambdasOnASingleLine: All
AllowShortLoopsOnASingleLine: true
AlwaysBreakAfterReturnType: None
AlwaysBreakTemplateDeclarations: Yes
BreakBeforeBraces: Custom
BraceWrapping:
AfterCaseLabel: false
AfterClass: false
AfterControlStatement: Never
AfterEnum: false
AfterFunction: false
AfterNamespace: false
AfterUnion: false
BeforeCatch: false
BeforeElse: false
IndentBraces: false
SplitEmptyFunction: false
SplitEmptyRecord: true
BreakBeforeBinaryOperators: None
BreakBeforeTernaryOperators: true
BreakConstructorInitializers: BeforeColon
BreakInheritanceList: BeforeColon
ColumnLimit: 0
CompactNamespaces: false
ContinuationIndentWidth: 8
IndentCaseLabels: true
IndentPPDirectives: None
IndentWidth: 4
KeepEmptyLinesAtTheStartOfBlocks: true
MaxEmptyLinesToKeep: 2
NamespaceIndentation: All
ObjCSpaceAfterProperty: false
ObjCSpaceBeforeProtocolList: true
PointerAlignment: Right
ReflowComments: false
SpaceAfterCStyleCast: true
SpaceAfterLogicalNot: false
SpaceAfterTemplateKeyword: false
SpaceBeforeAssignmentOperators: true
SpaceBeforeCpp11BracedList: false
SpaceBeforeCtorInitializerColon: true
SpaceBeforeInheritanceColon: true
SpaceBeforeParens: ControlStatements
SpaceBeforeRangeBasedForLoopColon: true
SpaceInEmptyParentheses: false
SpacesBeforeTrailingComments: 1
SpacesInAngles: false
SpacesInCStyleCastParentheses: false
SpacesInContainerLiterals: false
SpacesInParentheses: false
SpacesInSquareBrackets: false
TabWidth: 4
UseTab: Never

View File

@ -0,0 +1,5 @@
FROM wiiuenv/devkitppc:20230218
COPY --from=wiiuenv/wiiupluginsystem:20230215 /artifacts $DEVKITPRO
WORKDIR project

View File

@ -18,7 +18,7 @@ WUT_ROOT := $(DEVKITPRO)/wut
# DATA is a list of directories containing data files # DATA is a list of directories containing data files
# INCLUDES is a list of directories containing header files # INCLUDES is a list of directories containing header files
#------------------------------------------------------------------------------- #-------------------------------------------------------------------------------
TARGET := $(notdir $(CURDIR)) TARGET := ExamplePlugin
BUILD := build BUILD := build
SOURCES := src src/utils SOURCES := src src/utils
DATA := data DATA := data

View File

@ -1,11 +1,57 @@
# Example plugin # Example plugin
This is just a simple example plugin which can be used as a template. This is just a simple example plugin which can be used as a template.
The plugin logs the FSOpenFile calls via UDP (**Only when build via `make DEBUG=1`**).
The logging can be enabled/disabled via the WUPS Config menu (press L, DPAD Down and Minus on the GamePad, Pro Controller or Classic Controller).
## Installation
(`[ENVIRONMENT]` is a placeholder for the actual environment name.)
1. Copy the file `ExamplePlugin.wps` into `sd:/wiiu/environments/[ENVIRONMENT]/plugins`.
2. Requires the [WiiUPluginLoaderBackend](https://github.com/wiiu-env/WiiUPluginLoaderBackend) in `sd:/wiiu/environments/[ENVIRONMENT]/modules`.
Start the environment (e.g Aroma) and the backend should load the plugin.
## Building ## Building
For building you need: For building you need:
- [wups](https://github.com/Maschell/WiiUPluginSystem) - [wups](https://github.com/Maschell/WiiUPluginSystem)
- [wut](https://github.com/decaf-emu/wut) - [wut](https://github.com/devkitpro/wut)
Install them (in this order) according to their README's. Don't forget the dependencies of the libs itself. Install them (in this order) according to their README's. Don't forget the dependencies of the libs itself.
Then you should be able to compile via `make` (with no logging) or `make DEBUG=1` (with logging).
## Buildflags
### Logging
Building via `make` only logs errors (via OSReport). To enable logging via the [LoggingModule](https://github.com/wiiu-env/LoggingModule) set `DEBUG` to `1` or `VERBOSE`.
`make` Logs errors only (via OSReport).
`make DEBUG=1` Enables information and error logging via [LoggingModule](https://github.com/wiiu-env/LoggingModule).
`make DEBUG=VERBOSE` Enables verbose information and error logging via [LoggingModule](https://github.com/wiiu-env/LoggingModule).
If the [LoggingModule](https://github.com/wiiu-env/LoggingModule) is not present, it'll fallback to UDP (Port 4405) and [CafeOS](https://github.com/wiiu-env/USBSerialLoggingModule) logging.
## Building using the Dockerfile
It's possible to use a docker image for building. This way you don't need anything installed on your host system.
```
# Build docker image (only needed once)
docker build . -t example-plugin-builder
# make
docker run -it --rm -v ${PWD}:/project example-plugin-builder make DEBUG=1
# make clean
docker run -it --rm -v ${PWD}:/project example-plugin-builder make clean
```
## Format the code via docker
`docker run --rm -v ${PWD}:/src wiiuenv/clang-format:13.0.0-2 -r ./src -i`

View File

@ -1,13 +1,7 @@
#include "utils/logger.h"
#include <coreinit/filesystem.h> #include <coreinit/filesystem.h>
#include <coreinit/thread.h>
#include <coreinit/time.h>
#include <malloc.h> #include <malloc.h>
#include <string.h> #include <string.h>
#include <utils/logger.h>
#include <whb/libmanager.h>
#include <whb/log_cafe.h>
#include <whb/log_module.h>
#include <whb/log_udp.h>
#include <wups.h> #include <wups.h>
#include <wups/config/WUPSConfigItemBoolean.h> #include <wups/config/WUPSConfigItemBoolean.h>
@ -21,6 +15,8 @@ WUPS_PLUGIN_VERSION("v1.0");
WUPS_PLUGIN_AUTHOR("Maschell"); WUPS_PLUGIN_AUTHOR("Maschell");
WUPS_PLUGIN_LICENSE("BSD"); WUPS_PLUGIN_LICENSE("BSD");
#define LOG_FS_OPEN_CONFIG_ID "logFSOpen"
/** /**
All of this defines can be used in ANY file. All of this defines can be used in ANY file.
It's possible to split it up into multiple files. It's possible to split it up into multiple files.
@ -28,18 +24,16 @@ WUPS_PLUGIN_LICENSE("BSD");
**/ **/
WUPS_USE_WUT_DEVOPTAB(); // Use the wut devoptabs WUPS_USE_WUT_DEVOPTAB(); // Use the wut devoptabs
WUPS_USE_STORAGE("example_plugin"); // Unqiue id for the storage api WUPS_USE_STORAGE("example_plugin"); // Unique id for the storage api
bool logFSOpen = true; bool logFSOpen = true;
/** /**
Get's called ONCE when the loader exits, but BEFORE the ON_APPLICATION_START gets called or functions are overridden. Gets called ONCE when the plugin was loaded.
**/ **/
INITIALIZE_PLUGIN() { INITIALIZE_PLUGIN() {
if (!WHBLogModuleInit()) { // Logging only works when compiled with `make DEBUG=1`. See the README for more information.
WHBLogCafeInit(); initLogging();
WHBLogUdpInit();
}
DEBUG_FUNCTION_LINE("INITIALIZE_PLUGIN of example_plugin!"); DEBUG_FUNCTION_LINE("INITIALIZE_PLUGIN of example_plugin!");
// Open storage to read values // Open storage to read values
@ -48,9 +42,9 @@ INITIALIZE_PLUGIN() {
DEBUG_FUNCTION_LINE("Failed to open storage %s (%d)", WUPS_GetStorageStatusStr(storageRes), storageRes); DEBUG_FUNCTION_LINE("Failed to open storage %s (%d)", WUPS_GetStorageStatusStr(storageRes), storageRes);
} else { } else {
// Try to get value from storage // Try to get value from storage
if ((storageRes = WUPS_GetBool(nullptr, "logFSOpen", &logFSOpen)) == WUPS_STORAGE_ERROR_NOT_FOUND) { if ((storageRes = WUPS_GetBool(nullptr, LOG_FS_OPEN_CONFIG_ID, &logFSOpen)) == WUPS_STORAGE_ERROR_NOT_FOUND) {
// Add the value to the storage if it's missing. // Add the value to the storage if it's missing.
if (WUPS_StoreBool(nullptr, "logFSOpen", logFSOpen) != WUPS_STORAGE_ERROR_SUCCESS) { if (WUPS_StoreBool(nullptr, LOG_FS_OPEN_CONFIG_ID, logFSOpen) != WUPS_STORAGE_ERROR_SUCCESS) {
DEBUG_FUNCTION_LINE("Failed to store bool"); DEBUG_FUNCTION_LINE("Failed to store bool");
} }
} else if (storageRes != WUPS_STORAGE_ERROR_SUCCESS) { } else if (storageRes != WUPS_STORAGE_ERROR_SUCCESS) {
@ -62,11 +56,11 @@ INITIALIZE_PLUGIN() {
DEBUG_FUNCTION_LINE("Failed to close storage"); DEBUG_FUNCTION_LINE("Failed to close storage");
} }
} }
deinitLogging();
} }
/** /**
Gets called when the plugin loader is re-entered => when the plugin is unloaded. Gets called when the plugin will be unloaded.
The overridden functions are restored before this is getting called.
**/ **/
DEINITIALIZE_PLUGIN() { DEINITIALIZE_PLUGIN() {
DEBUG_FUNCTION_LINE("DEINITIALIZE_PLUGIN of example_plugin!"); DEBUG_FUNCTION_LINE("DEINITIALIZE_PLUGIN of example_plugin!");
@ -74,34 +68,39 @@ DEINITIALIZE_PLUGIN() {
/** /**
Gets called when an application starts. Gets called when an application starts.
This is called BEFORE the functions are overridden.
Make sure to initialize all functions you're using in the overridden functions!
**/ **/
ON_APPLICATION_START() { ON_APPLICATION_START() {
if (!WHBLogModuleInit()) { initLogging();
WHBLogCafeInit();
WHBLogUdpInit();
}
DEBUG_FUNCTION_LINE("ON_APPLICATION_START of example_plugin!"); DEBUG_FUNCTION_LINE("ON_APPLICATION_START of example_plugin!");
} }
/**
* Gets called when an application actually ends
*/
ON_APPLICATION_ENDS() {
deinitLogging();
}
/** /**
Gets called when an application request to exit. Gets called when an application request to exit.
**/ **/
ON_APPLICATION_REQUESTS_EXIT() { ON_APPLICATION_REQUESTS_EXIT() {
DEBUG_FUNCTION_LINE("ON_APPLICATION_REQUESTS_EXIT of example_plugin!"); DEBUG_FUNCTION_LINE_INFO("ON_APPLICATION_REQUESTS_EXIT of example_plugin!");
} }
/**
* Callback that will be called if the config has been changed
*/
void logFSOpenChanged(ConfigItemBoolean *item, bool newValue) { void logFSOpenChanged(ConfigItemBoolean *item, bool newValue) {
DEBUG_FUNCTION_LINE("New value in logFSOpenChanged: %d", newValue); DEBUG_FUNCTION_LINE_INFO("New value in logFSOpenChanged: %d", newValue);
logFSOpen = newValue; logFSOpen = newValue;
// If the value has changed, we store it in the storage. // If the value has changed, we store it in the storage.
WUPS_StoreInt(nullptr, "logFSOpen", logFSOpen); WUPS_StoreInt(nullptr, LOG_FS_OPEN_CONFIG_ID, logFSOpen);
} }
WUPS_GET_CONFIG() { WUPS_GET_CONFIG() {
// We open the storage so we can persist the configuration the user did. // We open the storage, so we can persist the configuration the user did.
if (WUPS_OpenStorage() != WUPS_STORAGE_ERROR_SUCCESS) { if (WUPS_OpenStorage() != WUPS_STORAGE_ERROR_SUCCESS) {
DEBUG_FUNCTION_LINE("Failed to open storage"); DEBUG_FUNCTION_LINE("Failed to open storage");
return 0; return 0;
@ -113,7 +112,7 @@ WUPS_GET_CONFIG() {
WUPSConfigCategoryHandle cat; WUPSConfigCategoryHandle cat;
WUPSConfig_AddCategoryByNameHandled(config, "Logging", &cat); WUPSConfig_AddCategoryByNameHandled(config, "Logging", &cat);
WUPSConfigItemBoolean_AddToCategoryHandled(config, cat, "logFSOpen", "Log FSOpen calls", logFSOpen, &logFSOpenChanged); WUPSConfigItemBoolean_AddToCategoryHandled(config, cat, LOG_FS_OPEN_CONFIG_ID, "Log FSOpen calls", logFSOpen, &logFSOpenChanged);
return config; return config;
} }
@ -121,14 +120,14 @@ WUPS_GET_CONFIG() {
WUPS_CONFIG_CLOSED() { WUPS_CONFIG_CLOSED() {
// Save all changes // Save all changes
if (WUPS_CloseStorage() != WUPS_STORAGE_ERROR_SUCCESS) { if (WUPS_CloseStorage() != WUPS_STORAGE_ERROR_SUCCESS) {
DEBUG_FUNCTION_LINE("Failed to close storage"); DEBUG_FUNCTION_LINE_ERR("Failed to close storage");
} }
} }
/** /**
This defines a function replacement. This defines a function replacement.
It allows to replace the system function with an own function. It allows to replace the system function with an own function.
So whenever a game / application calles an overridden function, your function gets called instead. So whenever a game / application calls an overridden function, your function gets called instead.
Currently it's only possible to override functions that are loaded from .rpl files of OSv10 (00050010-1000400A). Currently it's only possible to override functions that are loaded from .rpl files of OSv10 (00050010-1000400A).
@ -138,7 +137,7 @@ WUPS_CONFIG_CLOSED() {
} }
Within this macro, two more function get declare you can use. Within this macro, two more function get declare you can use.
my_ARBITRARY_NAME_OF_FUNCTION and real_FSOpenFile my_ARBITRARY_NAME_OF_FUNCTION and real_ARBITRARY_NAME_OF_FUNCTION
RETURN_TYPE my_ARBITRARY_NAME_OF_FUNCTION(ARGS_SEPERATED_BY_COMMA): RETURN_TYPE my_ARBITRARY_NAME_OF_FUNCTION(ARGS_SEPERATED_BY_COMMA):
is just name of the function that gets declared in this macro. is just name of the function that gets declared in this macro.
@ -147,16 +146,14 @@ WUPS_CONFIG_CLOSED() {
RETURN_TYPE real_ARBITRARY_NAME_OF_FUNCTION(ARGS_SEPERATED_BY_COMMA): RETURN_TYPE real_ARBITRARY_NAME_OF_FUNCTION(ARGS_SEPERATED_BY_COMMA):
is the name of the function, that leads to function that was overridden. is the name of the function, that leads to function that was overridden.
Use this to call the original function that will be overridden. Use this to call the original function that will be overridden.
CAUTION: Other plugins may already have manipulated the the return value or arguments. CAUTION: Other plugins may already have manipulated the return value or arguments.
Use this macro for each function you want to override Use this macro for each function you want to override
**/ **/
DECL_FUNCTION(int, FSOpenFile, FSClient *pClient, FSCmdBlock *pCmd, const char *path, const char *mode, int *handle, int error) { DECL_FUNCTION(int, FSOpenFile, FSClient *pClient, FSCmdBlock *pCmd, const char *path, const char *mode, int *handle, int error) {
int result = real_FSOpenFile(pClient, pCmd, path, mode, handle, error); int result = real_FSOpenFile(pClient, pCmd, path, mode, handle, error);
if (logFSOpen) { if (logFSOpen) {
DEBUG_FUNCTION_LINE("FSOpenFile called for folder %s! Result %d", path, result); DEBUG_FUNCTION_LINE_INFO("FSOpenFile called for folder %s! Result %d", path, result);
} }
return result; return result;
} }

View File

@ -0,0 +1,36 @@
#ifdef DEBUG
#include <stdint.h>
#include <whb/log_cafe.h>
#include <whb/log_module.h>
#include <whb/log_udp.h>
uint32_t moduleLogInit = false;
uint32_t cafeLogInit = false;
uint32_t udpLogInit = false;
#endif // DEBUG
void initLogging() {
#ifdef DEBUG
if (!(moduleLogInit = WHBLogModuleInit())) {
cafeLogInit = WHBLogCafeInit();
udpLogInit = WHBLogUdpInit();
}
#endif // DEBUG
}
void deinitLogging() {
#ifdef DEBUG
if (moduleLogInit) {
WHBLogModuleDeinit();
moduleLogInit = false;
}
if (cafeLogInit) {
WHBLogCafeDeinit();
cafeLogInit = false;
}
if (udpLogInit) {
WHBLogUdpDeinit();
udpLogInit = false;
}
#endif // DEBUG
}

View File

@ -1,29 +1,73 @@
#pragma once #pragma once
#include <coreinit/debug.h>
#include <string.h>
#include <whb/log.h>
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
#include <string.h> #define LOG_APP_TYPE "P"
#include <whb/log.h> #define LOG_APP_NAME "ExamplePlugin"
#define __FILENAME_X__ (strrchr(__FILE__, '\\') ? strrchr(__FILE__, '\\') + 1 : __FILE__) #define __FILENAME__ ({ \
#define __FILENAME__ (strrchr(__FILE__, '/') ? strrchr(__FILE__, '/') + 1 : __FILENAME_X__) const char *__filename = __FILE__; \
const char *__pos = strrchr(__filename, '/'); \
if (!__pos) __pos = strrchr(__filename, '\\'); \
__pos ? __pos + 1 : __filename; \
})
#define OSFATAL_FUNCTION_LINE(FMT, ARGS...) \ #define LOG(LOG_FUNC, FMT, ARGS...) LOG_EX_DEFAULT(LOG_FUNC, "", "", FMT, ##ARGS)
#define LOG_EX_DEFAULT(LOG_FUNC, LOG_LEVEL, LINE_END, FMT, ARGS...) LOG_EX(__FILENAME__, __FUNCTION__, __LINE__, LOG_FUNC, LOG_LEVEL, LINE_END, FMT, ##ARGS)
#define LOG_EX(FILENAME, FUNCTION, LINE, LOG_FUNC, LOG_LEVEL, LINE_END, FMT, ARGS...) \
do { \ do { \
OSFatal_printf("[%s]%s@L%04d: " FMT "", __FILENAME__, __FUNCTION__, __LINE__, ##ARGS); \ LOG_FUNC("[(%s)%18s][%23s]%30s@L%04d: " LOG_LEVEL "" FMT "" LINE_END, LOG_APP_TYPE, LOG_APP_NAME, FILENAME, FUNCTION, LINE, ##ARGS); \
} while (0) } while (0)
#define DEBUG_FUNCTION_LINE(FMT, ARGS...) \ #ifdef DEBUG
do { \
WHBLogPrintf("[%23s]%30s@L%04d: " FMT "", __FILENAME__, __FUNCTION__, __LINE__, ##ARGS); \
} while (0);
#define DEBUG_FUNCTION_LINE_WRITE(FMT, ARGS...) \ #ifdef VERBOSE_DEBUG
do { \ #define DEBUG_FUNCTION_LINE_VERBOSE(FMT, ARGS...) LOG(WHBLogPrintf, FMT, ##ARGS)
WHBLogWritef("[%23s]%30s@L%04d: " FMT "", __FILENAME__, __FUNCTION__, __LINE__, ##ARGS); \ #define DEBUG_FUNCTION_LINE_VERBOSE_EX(FILENAME, FUNCTION, LINE, FMT, ARGS...) LOG_EX(FILENAME, FUNCTION, LINE, WHBLogPrintf, "", "", FMT, ##ARGS);
} while (0); #else
#define DEBUG_FUNCTION_LINE_VERBOSE(FMT, ARGS...) while (0)
#define DEBUG_FUNCTION_LINE_VERBOSE_EX(FMT, ARGS...) while (0)
#endif
#define DEBUG_FUNCTION_LINE(FMT, ARGS...) LOG(WHBLogPrintf, FMT, ##ARGS)
#define DEBUG_FUNCTION_LINE_WRITE(FMT, ARGS...) LOG(WHBLogWritef, FMT, ##ARGS)
#define DEBUG_FUNCTION_LINE_ERR(FMT, ARGS...) LOG_EX_DEFAULT(WHBLogPrintf, "##ERROR## ", "", FMT, ##ARGS)
#define DEBUG_FUNCTION_LINE_WARN(FMT, ARGS...) LOG_EX_DEFAULT(WHBLogPrintf, "##WARN ## ", "", FMT, ##ARGS)
#define DEBUG_FUNCTION_LINE_INFO(FMT, ARGS...) LOG_EX_DEFAULT(WHBLogPrintf, "##INFO ## ", "", FMT, ##ARGS)
#define DEBUG_FUNCTION_LINE_ERR_LAMBDA(FILENAME, FUNCTION, LINE, FMT, ARGS...) LOG_EX(FILENAME, FUNCTION, LINE, WHBLogPrintf, "##ERROR## ", "", FMT, ##ARGS);
#else
#define DEBUG_FUNCTION_LINE_VERBOSE_EX(FMT, ARGS...) while (0)
#define DEBUG_FUNCTION_LINE_VERBOSE(FMT, ARGS...) while (0)
#define DEBUG_FUNCTION_LINE(FMT, ARGS...) while (0)
#define DEBUG_FUNCTION_LINE_WRITE(FMT, ARGS...) while (0)
#define DEBUG_FUNCTION_LINE_ERR(FMT, ARGS...) LOG_EX_DEFAULT(OSReport, "##ERROR## ", "\n", FMT, ##ARGS)
#define DEBUG_FUNCTION_LINE_WARN(FMT, ARGS...) LOG_EX_DEFAULT(OSReport, "##WARN ## ", "\n", FMT, ##ARGS)
#define DEBUG_FUNCTION_LINE_INFO(FMT, ARGS...) LOG_EX_DEFAULT(OSReport, "##INFO ## ", "\n", FMT, ##ARGS)
#define DEBUG_FUNCTION_LINE_ERR_LAMBDA(FILENAME, FUNCTION, LINE, FMT, ARGS...) LOG_EX(FILENAME, FUNCTION, LINE, OSReport, "##ERROR## ", "\n", FMT, ##ARGS);
#endif
void initLogging();
void deinitLogging();
#ifdef __cplusplus #ifdef __cplusplus
} }