# Altirra Build Instructions

## Prerequisites

### Build machine

- Required: Windows 7 x64 or newer
- Recommended: Windows 10 x64
- Not supported: Windows XP or Vista (cannot run toolchain)

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.

### Compiler

- Recommended: Visual Studio 2015 Update 3 (Professional or Community)

- Windows 8.1 SDK and XP targeting features required

- Not supported: VS2015 pre-Update 2
- Not supported: VS2013 or earlier
- Not supported: MinGW/GCC/Clang

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.

### DirectX SDK

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.

### Additional Tools

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.

## Build environment setup

### Build location

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.

### Local configuration

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.

### Platform setup

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.

### MADS Assembler

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.

### YASM Assembler

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.

## Building

### First time

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.

### Build targets

There are end projects that can be built from the two solution files:

- Altirra: This is the main computer emulator.
- AltirraShell: This is the device emulator.
- ATHelpFile: Help file for the computer emulator.

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.

### Output locations and debugging setup

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.

### Possible failures

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.

### Release script

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.

## Deployment

### Licensing

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.

### Third party content

The following third party content is present in Altirra with the following licences, believed to be GPL-compatible:

- `system\source\hash.cpp`: MurmurHash3 (public domain; see source for reference)
- `Kasumi\data\Tuffy.ttf`: Tuffy TrueType font (public domain; see Tuffy.txt for reference)

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.

### Deployment dependencies

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.