Windows 7 x64 or newer is recommended as the build OS. Windows 8.1 x64 and Windows 10 x64 have been tested as of this writing. 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 2013 Professional Update 5. VS2015 Professional and Community Update 1 are also supported and can also be used. (As of this writing, the dev enviroment is actually VS2015u1 building with the VS2013u4 compiler.)
Visual C++ Express for Desktop can 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.
The latest standalone distribution of the DirectX SDK, June 2010, is required. The Windows 8 SDK is not sufficient as it does not include D3DX9. The development runtime must be installed on the build machine as the build process compiles shaders.
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. 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 VS2013 compiler with XP targeting enabled (v120_xp). Either the VS2013 or VS2015 IDE can be used with this toolchain. To use the VS2015 compiler, edit PlatformSetup.props to select v140_xp instead. 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.
The makefile-based projects will report (Visual Studio 2013) regardless; this is due to a Visual Studio quirk and can be ignored, as those projects do not actually use the C++ toolchain and will build even if the VS2013 toolchain is not installed. If necessary to improve cosmetics, the label may be removed by manually editing the .vcxproj file to match the version of the Visual Studio IDE in use.
By default, the build process will attempt to source the DirectX SDK from the user props and 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 three targets that can be built from the two solution files:
For the emulators, three configurations are supported: Debug (unoptimized), Profile (optimized), and Release (LTCG).
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.
asuka.exe will fail to run in the build if the DirectX Developer Runtime is not installed or the version of D3DX associated with the DirectX SDK being used is not installed.
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 VS2013 Update 4. 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 library. It is used in the build, but only the build tools link to D3DX 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.