Building from Source

Building from source

The upcoming 1.10 application is a Windows C++ program using MSVC, FreeGLUT/OpenGL, Windows APIs, and static vcpkg dependencies. Both the checked-in Visual Studio solution and CMake now include embedded SYNCore output and MP4 export.

Clone with all submodules

git clone --branch develop --recurse-submodules https://github.com/DixelU/SAFC.git
cd SAFC

For an existing clone:

git submodule update --init --recursive

The checkout uses the shared utility headers, the SYNCore submodule, and SYNCore's own third_party/utility submodule. Keep the revisions recorded by the checkout. Initializing only the top-level submodules is insufficient for SYNCore.

Match the toolchain to the checkout

The Visual Studio project requests:

• MSVC platform toolset v145.
• Windows SDK 10.0.26100.0.
• C++23 mode (stdcpp23).
• Static vcpkg triplets: x64-windows-static or x86-windows-static.

Install the matching C++ build components, or deliberately retarget a local copy and validate that configuration yourself. Older README text mentions MSVC 2022; the project file in the version being built is the more precise reference.

For CMake, the repository-root entry point requires CMake 3.30 or newer; configuring _SAFC_ directly requires 4.1 or newer. Your CMake version must also support the Visual Studio generator you select.

Dependencies

From a configured vcpkg installation, install the architecture you intend to build:

vcpkg install boost:x64-windows-static freeglut:x64-windows-static libarchive:x64-windows-static zstd:x64-windows-static
vcpkg integrate install

For a 32-bit solution build, use the corresponding x86-windows-static triplets. The project uses classic vcpkg integration, not a manifest. The checked-in dependencies.txt still lists Boost, FreeGLUT, and LibArchive; zstd is also explicitly required by the current archive-player sources and CMake configuration.

MP4 encoding uses Windows Media Foundation libraries from the Windows SDK (mfplat, mfreadwrite, mfuuid, and mf). No external FFmpeg executable is used by this exporter.

Visual Studio solution

Open _SAFC_.sln, select Release / x64, and build. Alternatively, from a Visual Studio Developer PowerShell with MSBuild available, run this from the repository root:

MSBuild.exe .\_SAFC_.sln /m /t:Build /p:Configuration=Release /p:Platform=x64 /verbosity:minimal

The expected executable is x64\Release\SAFC.exe. For the solution's 32-bit configuration, use /p:Platform=x86 with the x86 dependencies. The solution maps x86 to the project's Win32 configuration.

The solution automatically enables embedded SYNCore when SYNCore\SAFSYN\windows_synth.cpp is present. Without that submodule, it builds with WinMM output only; embedded synthesis and MP4 export are unavailable.

CMake

Run from the repository root in a Developer PowerShell. Replace C:/path/to/vcpkg with the actual vcpkg directory, and choose an installed Visual Studio generator with the required compiler:

cmake -S . -B build/safc-1.10 -A x64 -DCMAKE_TOOLCHAIN_FILE=C:/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows-static -DSAFC_ENABLE_SYNCORE=ON
cmake --build build/safc-1.10 --config Release --target SAFC

For a Visual Studio multi-configuration build, this produces build\safc-1.10\Release\SAFC.exe. If you configure with -S _SAFC_ instead, the application target and executable are named _SAFC_.

SAFC_ENABLE_SYNCORE defaults to ON. Set it to OFF for a WinMM-only build. If the SYNCore directory is missing, CMake warns and proceeds without embedded output; if SYNCore is present but its nested utility headers are missing, configuration fails. Initialize the submodules and reconfigure to restore the full feature set.

Both CMake entry points now include the editor tools, archive playback, SYNCore integration, and video-export sources. They remain Windows application builds; the CMake files do not establish a working Linux port.

Optional MP4 exporter regression test

With SYNCore enabled, configure the Windows exporter test and run its registered CTest case:

cmake -S . -B build/safc-1.10 -DSAFC_BUILD_VIDEO_EXPORT_TESTS=ON
cmake --build build/safc-1.10 --config Release --target safc-video-export-tests
ctest --test-dir build/safc-1.10 -C Release -R "^safc-video-export$" --output-on-failure

These commands reuse the toolchain and architecture from the earlier configure step. The test exercises exporter behavior; it does not cover every GUI action, MIDI device, bank, or large score. SYNCore's own test suite is disabled by SAFC's CMake integration and can be built separately in that submodule.

Build caveats

• Missing utility or long_uint.h headers usually mean a required submodule was not initialized.
• Missing GL/freeglut.h, archive.h, or zstd.h, or unresolved library symbols, require checking vcpkg integration, architecture, and installed triplets first.
• Some library-directory entries in the Visual Studio project refer to C:\dev\vcpkg\installed. Review them if your installation differs.
• A build without SYNCore (embedded) in its output list cannot use the embedded synth or MP4 export. Check the submodule and build options before troubleshooting a sound bank.
• A successful build does not test file preservation or performance on large scores. Check those separately with representative files.

Build instructions were checked against the 1.10 development sources on 6 September 2026, including the root CMake configuration. They are not a claim of a clean-machine build or validation of every architecture.