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.
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 build system is configured by a tree of property sheets and as of 2.90 supports configuration overrides that can be set without changing the base source files. This permits local configuration without having to alter files within source code control. All overrides are placed in the localconfig/active folder, with examples that can be copied from the localconfig/example folder. Note that the overrides are applied on top of instead of replacing the standard .props files.
When using source code control, you may find it convenient to put localconfig/active/* in the "ignore" configuration file of your VCS so it will not pick up files in that folder for submission.
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 control the toolchain instead.
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.
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 or PlatformSetup.local.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 mads.exe from PATH. This can be overridden in the ATMadsPath property of localconfig/active/Altirra.local.props. Use localconfig/example/Altirra.local.props as a reference.
By default, the build process will attempt to source yasm.exe from PATH. This can be overridden in the YASMPath property of localconfig/active/YASM.local.props. Use localconfig/example/YASM.local.props as a reference.
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 the expected version. 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.