As of 4.20, building on a 32-bit (x86) system is no longer supported.
The following components are required to minimally build Altirra:
VS2019 or earlier, MinGW, GCC, and Clang compilers are not supported.
Additional components to compile for Windows on ARM (ARM64) (not AMD64):
Additional components to compile the help file:
Additional components to run the release script (release.py) and auxiliary scripts:
If you had set up to build earlier versions of Altirra, these are no longer required in 4.10 and can be omitted:
If you have the DirectX SDK in your default VC++ Directories setup, make sure that its include headers are lower priority than the Windows SDK per Microsoft's integration guidelines. Otherwise, you can get compile warnings or errors due to it overriding newer DXGI headers from the Windows SDK.
Newer versions of these tools should work but have not been tested. Older versions should be avoided; some older versions of MADS, for instance, will either fail to build the AltirraOS kernel or will introduce subtle corruption into floating point constants in the math pack.
Altirra should build in a path that has spaces, but that's not tested, and the build may blow up -- so it's better just to build it in a folder where the path has no spaces.
The build projects are set up to allow project settings to be altered without needing to change the base project files or change each project individually. This is optional, but is done by placing property sheet files in the localconfig/active folder. Use the examples in the localconfig/example folder as a starting point.
Visual Studio doesn't always pick up changes to .props files while open, so make sure to restart the IDE after adding or changing any such file.
By default, the build process will attempt to source mads.exe from PATH. However, you might not want it in PATH, in which case you can override the path to it in the ATMadsPath property of localconfig/active/Altirra.local.props. Use localconfig/example/Altirra.local.props as a reference.
The build is preconfigured to use the Visual Studio 2022 compiler (v143). The src/build/PlatformSetup.props file is designed to make it easy to change this if you want to try a different compiler, such as a future version of Visual C++ or LLVM/Clang.
To switch the toolchain locally, create localconfig/active/PlatformSetup.local.props and modify the toolchain setting in it. Use localconfig/example/PlatformSetup.local.props as a reference. All projects will be switched over to the new setting.
You shouldn't get a dialog from Visual Studio offering to upgrade the projects. If you do, don't do it -- it will break the platform setup in the project files. Use the instructions above instead.
Open Altirra.sln and set the startup project to Altirra within the Native Projects folder in the Solution Explorer.
Change the active solution configuration and platform to Release x86 and build it first. This is needed to build some common build tools that are used by other configurations/platforms. After that, you can build other configurations such as Debug x86 or Release x64.
There are end projects that can be built from the three solution files:
These projects have no direct dependency on each other, and the "run only startup" option in Visual Studio can be used to avoid having to build both Altirra and AltirraShell on every modification.
For the emulators, three configurations are supported: Debug (unoptimized), Profile (optimized), and Release (LTCG). Debug is noticeably slower, but the performance difference between Profile and Release is minor.
The final program and other build outputs go to the out folder.
Intermediate build artifacts like .obj files go to the obj folder, and libraries to the lib folder. You can freely delete these as needed.
Link failures usually mean that an upstream project or file failed to build. Visual Studio has an unfortunate tendency to uselessly attempt linking a project whose dependencies have failed, so always look for the first error.
For shipping builds, the release script (release.py) automates the process of generating and packaging a clean build. It is meant to be run in a Visual Studio Developer Command Prompt. Run it with py release.py for usage.
Please note that Altirra is licensed under the GNU General Public License, version 2 or above. All rebuilt versions of it must be distributed under compatible conditions. The source code for the rebuilt version must be made available per the terms of the GPL for any released binaries. This is true even for pre-release versions.
A few source code files have licenses that are more permissive than the GPL, and may be used as such on their own. This only applies to the files that have a block comment at the top describing the more permissive license option. In particular, the system library and much of the 6502-based code is licensed more permissively.
The RMT plugins, and the libraries used in those RMT plugins, have a special license exception added to the GPLv2 to explicitly allow their use with Raster Music Tracker. This applies only to the libraries that have that exception in their source files.
The following third party content is present in Altirra with the following licences, believed to be GPL-compatible:
The Tuffy TrueType font is no longer used or included with Altirra as of 4.10.
In addition, the built-in kernel contains a copy of the Atari system bitmap font. This is believed to not be copyrightable, but concerned parties should consult a qualified legal advisor for the pertinent jurisdictions as the author cannot provide legal assurance. No other parts of the Atari system ROMs are included or derived from in the included source.
Altirra does not link with the Microsoft D3DX or D3DCompiler libraries. The latter is used in the build, but only the build tools link to D3DCompiler and the outputs are used without it.
Altirra is statically linked against all necessary runtimes. In particular, neither the DirectX nor Visual C++ Redistributable are needed with the final executable regardless of OS.
Since 2.90, the DirectX SDK is no longer necessary for the build as D3DCompiler from the Windows SDK is used instead. However, since D3DCompiler no longer supports shader model 1.x, the remaining vs/ps1.1 shaders have been included in precompiled form. The source has been included and they can be rebuilt with the included rebuildps11.cmd script, but doing so requires an older version of the DirectX SDK that still has psa.exe, since the latest SDK only includes fxc which can only compile HLSL.
Since D3DCompiler no longer supports shader model 1.x, the remaining vs/ps1.1 shaders have been included in precompiled form. The source has been included and they can be rebuilt with the included rebuildps11.cmd script, but doing so requires an older version of the DirectX SDK that still has psa.exe, since the latest SDK only includes fxc which can only compile HLSL.
If you really, really feel the need to edit the pixel shaders and don't want to install DXSDK November 2008 to get psa.exe, you can write a small wrapper around D3DXAssembleShader(). Sorry, but at this point even the author's tolerance for ps1.x is waning.