Windows 7 x64 or newer is required as the build OS, with Windows 10 x64 being recommended. XP and Vista are not supported due to IDE/compiler requirements. Building from an x86 system should work but is not tested or recommended, particularly since the x64 build cannot be tested on such a system.
The official build environment is Visual Studio 2015 Update 3, either Professional or Community Edition. The stock build configuration requires the Windows 8.1 SDK and the XP targeting features of Visual Studio to be installed. Visual Studio 2013 is no longer supported.
Visual C++ Express for Desktop can probably be used with a couple of caveats. The Windows SDK is required for the Win32/COM build environment and the resource editor is not available. Note that this is not a tested configuration and Community or Professional Edition is recommended instead.
The GCC/MinGW and Clang compilers are not currently supported and will not work. As of this writing, the latest preview version of Clang/C2 (July 2016) will not work either.
As of 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.
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.
YASM 1.3.0 is needed for x86/x64 assembly language modules. (http://yasm.tortall.net/)
MADS 1.9.8 is needed for 6502 assembly language modules. (http://mads.atari8.info/)
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.
The HTML Help 1.4 toolkit is required to build the help file. It should be automatically installed with recent versions of Visual Studio. If not, it is available as a separate download from Microsoft.
Altirra is designed to build in arbitrary locations, but don't attempt to build it under a path that has spaces. This hasn't been tested and may fail if some paths are not quoted. Attempting to do so is simply asking for unnecessary trouble.
The PlatformSetup.props file controls the platform toolset that is used to build the programs. This allows the toolchain for the entire solution to be switched with one property sheet. The normal Visual Studio dialog to offering to upgrade the projects to the newest compiler has been inhibited to prevent the converter from breaking this setup. If you still receive this dialog, do not upgrade the projects through it. This will break the toolchain switching setup in the projects. The PlatformSetup.props file should be used to switch the toolchain instead.
The build initially comes set to use the VS2015 compiler with XP targeting enabled (v140_xp).To use the VS2015 compiler without XP targeting, edit PlatformSetup.props to select v140 instead. This is necessary for Code Analysis. Note that Visual Studio should be restarted after editing any .props file manually as the IDE does not reliably recognize external changes to property files.
By default, the build process will attempt to source the assemblers from PATH.
To change the DirectX SDK location, edit DirectXSDK.props in a text editor to uncomment the compile/link settings and specify the required paths.
To change the YASM location, edit the command line templates in YASM.props.
To change the MADS location, edit the MADS variable in the two Makefiles.
The Release x86 configuration should be built first in a new environment as it is necessary to prebuild tools that are used in all configurations. After the build tools have been built once, any other configuration/platform can be built. This is necessary because the x64 build uses x86 tools to enable cross-compilation.
There are end projects that can be built from the two 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.
In general, compilation outputs go to the obj folder, library outputs to lib, and executables to out. A few files are also built into autogen folders within the projects. The end projects are set up to automatically default to the correct executable location to start debugging.
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.
If assembly language (.asm) files are failing to build, i.e. YASM returning a non-zero error code, this usually means that you don't have the path to YASM set up correctly.
For shipping builds, the release script (release.cmd) automates the process of generating and packaging a clean build. It is invoked in a Visual C++ build environment with the name of the version being released. The release script automatically injects the version string into the source tree, triggers a clean build, and then packages the result in the publish directory.
The release script checks the version of cl.exe available in the PATH and will fail if it is not VS2015 Update 3. Use /anyvc to bypass this check and force the current compiler to be used.
The packaging step requires the Info-Zip archiver (zip.exe) and the repacking tool advancecomp (advzip.exe) to generate the final .zip files.
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.
The following third party content is present in Altirra with the following licences, believed to be GPL-compatible:
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.