The C++17 wrapper of MajSimai, with MajSimai compiled by native AOT into a static library for each platform. The program contains the whole parser and needs no .NET runtime or MajSimai library at run time.
The wrapper is header-only and generated from the native ABI of MajSimai by
tools/MajSimai.CppGen, the way
FFmpeg.AutoGen generates C# bindings from the FFmpeg headers, so it always matches the exported structs.
The release workflow of MajSimai publishes everything here except this README: each MajSimai tag replaces the
packages, the root CMakeLists.txt (from
tools/MajSimaiCpp) and LICENSE, and tags
this repository with the same version. Do not edit them by hand; change MajSimai instead. This README is maintained
here and kept by each release.
add_subdirectory(MajSimaiCpp)
target_link_libraries(app PRIVATE MajSimai::MajSimaiCpp)The root CMakeLists.txt links the package of the target platform from packages/<rid>. Set
MAJSIMAI_RUNTIME_IDENTIFIER (such as win-x64) to choose one yourself.
| Package | Platform |
|---|---|
win-x64, win-arm64 |
Windows, MSVC |
linux-x64, linux-arm64 |
Linux (glibc) |
osx-x64, osx-arm64 |
macOS |
On Windows the native AOT runtime is compiled with the static release C runtime, so the program must use it too:
set(CMAKE_MSVC_RUNTIME_LIBRARY MultiThreaded) # before the targets are created#include <MajSimai/MajSimai.h>
// Copy the result into owned data
MajSimai::SimaiFile file = MajSimai::SimaiParser::Parse(text);
for (const auto& note : file.charts[4].noteTimings[0].notes)
{
bool star = note.isStar;
}
// Or read the native memory without copying it; `parsed` owns it and frees it when destroyed
MajSimai::ParsedSimaiFile parsed = MajSimai::SimaiParser::ParseAsView(text);
for (auto chart : parsed.GetFile().GetCharts())
{
for (auto timing : chart.GetNoteTimings())
{
for (auto note : timing.GetNotes())
{
std::string_view raw = note.GetRawContent();
}
}
}
// Strict mode throws on the first chart that breaks the grammar
MajSimai::SimaiParser::Parse(text, MajSimai::SimaiSyntaxTolerance::Strict);A failed parse throws MajSimai::SimaiParseException, with GetCode(), GetLine(), GetColumn() and GetContent().
Ownership:
ParsedSimaiFileis the only owner of a native result. It cannot be copied; moving it leaves the source empty (explicit operator boolis false andGetFile()throwsstd::logic_error).- Views (
SimaiFileView,SimaiNoteView,ArrayView,std::string_view) read the native memory and must not outlive theParsedSimaiFile.GetFile()is deleted on a temporary, soSimaiParser::ParseAsView(text).GetFile()does not compile;ParsedSimaiFileis not a view either, so it cannot be sliced into one. UseToModel()orSimaiParser::Parsefor data that outlives the result. - The result is owned by a
ParsedSimaiFileas soon as the native call returns, so it is freed even when building the exception throws. The native structs only have pointers toconstdata.
| Header | Content |
|---|---|
MajSimai.h |
SimaiParser, ParsedSimaiFile (owns the native result) and SimaiParseException |
MajSimai.Core.g.h |
The enums, the native structs and the exported functions, with static_asserts that every offset and size matches MajSimai on 64-bit platforms |
MajSimai.Views.g.h |
A view per struct (SimaiNoteView, ...) that reads the native memory without copying it |
MajSimai.Model.g.h |
An owned struct per native struct (SimaiNote, ...) with std::string and std::vector |
MajSimai.ArrayView.g.h |
ArrayView, the iterable view of a native array |
The commands in this section run in a clone of MajSimai.
tools/build-cpp-package.py publishes MajSimai with native AOT as a shared or static library and puts it next to a
freshly generated wrapper, with a CMakeLists.txt that links it:
python tools/build-cpp-package.py --kind shared # artifacts/cpp/<rid>-shared
python tools/build-cpp-package.py --kind static --verify # artifacts/cpp/<rid>-static, then builds and runs a test programadd_subdirectory(path/to/package)
target_link_libraries(app PRIVATE MajSimai::MajSimaiCpp)| Kind | What the package links |
|---|---|
shared |
lib/MajSimai.so (with the soname MajSimai.so, found through the rpath CMake sets) or lib/MajSimai.dylib; on Windows lib/MajSimai.lib with bin/MajSimai.dll, which the program needs next to it |
static |
lib/MajSimai.a (MajSimai.lib on Windows), then the native AOT runtime in lib/aot/ and the system libraries, in link order. The program contains the whole parser and needs no MajSimai library at run time |
The script reads the runtime libraries from the publish itself (tools/MajSimai.NativePackage.targets), so the package
matches the .NET SDK that built it, and writes them to MajSimaiNative.json; the generator turns that file into the
CMakeLists.txt (--native-manifest). Options: --rid, --output, --framework, --configuration, --version
(overrides the version in MajSimai.csproj). Native AOT needs a C++ toolchain and cannot cross-compile to another
operating system.
When a version tag is pushed, the release workflow of MajSimai (.github/workflows/main.yml) builds a static package
for each platform above, and pushes them to this repository under packages/<rid> with the root CMakeLists.txt in
tools/MajSimaiCpp, tagged with the same version; it keeps this README. It needs the secret MAJSIMAICPP_TOKEN, a token that can push to
MajSimaiCpp. To test it, run the workflow by hand (Actions → Run workflow, with an optional version such as
3.0.1-test): it builds everything, uploads the NuGet packages, the C++ packages and the content of MajSimaiCpp as
artifacts, and publishes nothing; the push to MajSimaiCpp is a dry run that still checks the token.
Without a package, add Bindings/Cpp of MajSimai and point it at a library you published yourself:
set(MAJSIMAI_NATIVE_LIBRARY "path/to/MajSimai.so") # MajSimai.lib on Windows, MajSimai.dylib on macOS
add_subdirectory(MajSimai/Bindings/Cpp)
target_link_libraries(app PRIVATE MajSimai::MajSimaiCpp)The generator reads the compiled ABI with reflection: it starts from the methods marked with
[UnmanagedCallersOnly(EntryPoint = ...)] and follows their parameters and fields to the structs and enums they use.
Run it after changing Runtime/Unmanaged; a test of MajSimai fails while Bindings/Cpp is out of date.
dotnet run --project tools/MajSimai.CppGen # writes Bindings/Cpp
dotnet run --project tools/MajSimai.CppGen -- --check # exits with 1 when Bindings/Cpp is out of dateThe ABI follows these rules, and the generator stops with a message that names the member when one is broken:
-
A pointer field says what it points to with an attribute. The field that holds the length is hidden in the views and models, and the pointer is declared as a pointer to
const.Attribute Field C++ view / model [NativeString(nameof(textLen))]byte*: UTF-8 text, length in bytesstd::string_view/std::string[NativeArray(nameof(itemsLen))]T*: an arrayArrayView/std::vector[NativePointee(typeof(T))]void*: oneT, only in the parse resultconst T* -
A data struct is named
Unmanaged<Name>; its view is<Name>Viewand its model<Name>. A struct that exported functions take by pointer (the parse result) gets no view or model. -
Structs use the default sequential layout. The generator measures every offset in .NET and checks that C++ gives the same one.
-
Exported functions set
CallConvsand only use blittable types:boolandcharare rejected in their signatures (they are fine as struct fields, which are not marshalled). -
XML documentation comments become Doxygen comments.
-
MajSimai.his written against fixed names (MajSimai_ParseWithTolerance,MajSimai_Free,SimaiSyntaxToleranceand the fields ofUnmanagedSimaiParseResult); the generator checks them before writing anything.
The C++ tests of MajSimai (see its README) compile the wrapper and link both kinds of package with GCC 13 and Clang 18
on Linux x64. The release workflow builds and runs a test program with each static package, except win-arm64, which
is cross-compiled on x64. 32-bit platforms are not supported, and 32-bit layouts are not checked by the
static_asserts.
GPL-3.0-or-later, as MajSimai.