Building from Source ‐ (Windows) - ApertureViewer/Aperture-Viewer GitHub Wiki

This build instructions page is adapted almost entirely from the Firestorm Viewer Wiki page for building on Windows. We gratefully acknowledge the Firestorm Viewer Project for providing these detailed instructions. Aperture Viewer's build process is very similar to Firestorm's due to its codebase being forked from Firestorm.

Please refer to the original Firestorm Viewer Wiki for the most up-to-date and potentially more detailed build instructions if needed.

Original Firestorm Windows Build Instructions Source: [Link to Firestorm Windows Compiling Wiki Page Here - If Available, otherwise link to Firestorm Wiki Home]

Firestorm Self Compilers Group: For community-based help and questions related to compiling viewers based on Firestorm, you can join the "Firestorm Self Compilers" group in Second Life: Firestorm Self Compilers

These tools are necessary for compiling any viewer based on the Linden Lab open-source code and only need to be installed once.

All installations should be done with default settings (unless explicitly stated otherwise). If you deviate from these defaults, you are responsible for troubleshooting any issues that may arise.

• Install Windows 10/11 64-bit using your own valid product key.

• Install Visual Studio 2022

  • Run the installer as Administrator (right-click, "Run as administrator").
  • On the "Workloads" tab, check "Desktop development with C++".
  • All other workload options can be unchecked.

  [!TIP] If you don't have a commercial edition of Visual Studio 2022, consider installing the free Community version.

• Download and install TortoiseGit 2.9.0 or newer (64-bit).
  • Note: There is no option to install as Administrator.
  • Use default options for path, components, etc.
  • During installation, it will prompt you to download and install Git for Windows.
    • Install Git for Windows with default options EXCEPT for "Configuring the line endings conversion": You MUST select "Checkout as-is, commit as-is" here!

• Download and install at least CMake 3.16.0.
  • Note: There is no option to install as Administrator.
  • At the "Install Options" screen, select "Add CMake to the system PATH for all users".
  • Use default options for everything else (path, etc.).
  • Verify that the following directory has been added to your system PATH environment variable:
    • For 64-bit version: C:\Program Files\CMake\bin
    • (32-bit version is no longer supported for building Aperture Viewer)

• Download and install Cygwin 64 (64-bit).
  • Run the installer as Administrator (right-click, "Run as administrator").
  • Use default options (path, components, etc.) until you reach the "Select Packages" screen.
  • Add the following additional package:
    • Devel/patch
  • Use default options for everything else.
  • Verify that the following directory has been added to your system PATH and that it is placed before "%SystemRoot%\system32":
    • C:\Cygwin64\bin

• Download and install the most recent version of Python 3.

  • Run the installer as Administrator (right-click, “Run as administrator”).
  • Tick "Add Python 3.x to PATH" (the installer should detect the latest 3.x version).
  • Choose the "Customize installation" option.
    • Ensure "pip" is ticked.
    • "Documentation", "tcl/tk and IDLE", "Python test suite", and "py launcher" are not required for compiling the viewer but can be selected if you wish.
    • On the "Advanced Options" screen, the correct options should already be ticked.
    • Set "Customize install location" to: C:\Python3
  • Verify that the following directory has been added to your system PATH: C:\Python3

  [!TIP] On Windows 10/11, you may want to disable the app alias for Python. Open the Windows Settings app, search for "Manage app execution aliases," and disable the alias for "python3.exe".

Confirm that the development tools are installed correctly. Open a Cygwin terminal and enter the following commands, one by one:

cmake --version
git --version
python --version
pip --version

If each command reports a valid version number and not "Command not found" errors, your tool installation is likely successful.

• Install Autobuild:
  • You can install Autobuild and its dependencies using the requirements.txt file in the Aperture Viewer repository. This ensures you use compatible versions used in official builds.
  • Open Windows Command Prompt and navigate to the root directory of your Aperture Viewer source code repository (e.g., C:\firestorm\phoenix-firestorm or C:\aperture-viewer if you renamed it).
  • Enter the command: pip install -r requirements.txt
  • Autobuild and its dependencies will be installed. It is crucial to install Autobuild as described here. Earlier methods of just adding source files to the PATH are no longer sufficient.
  • Alternatively, you can install directly from the Second Life Autobuild repository:
    • Open Windows Command Prompt and enter: pip install git+https://github.com/secondlife/autobuild.git#egg=autobuild
• Set Environment Variable AUTOBUILD_VSVER:
  • Set the environment variable AUTOBUILD_VSVER to 170 (This corresponds to Visual Studio 2022).
• Check Autobuild Version:
  • Open Windows Command Prompt and enter: autobuild --version
  • Verify that the output shows "autobuild 3.8" or higher.

• Install NSIS (Nullsoft Scriptable Install System):

  • Installation of NSIS is only required if you plan to create a Windows installer package (.exe) for Aperture Viewer. If you are just building for personal use and running directly, NSIS is not needed.
  • If you need to create an installer, download NSIS from the official NSIS website and install it.

  [!IMPORTANT] Unicode NSIS for Older Codebases (Generally Not Needed): If you are building Aperture Viewer based on a very old codebase (prior to the "Bugsplat merge" in Firestorm), you might need the Unicode version of NSIS from http://www.scratchpaper.com. However, for most current Aperture Viewer forks, the standard NSIS from the official NSIS website should be sufficient.

Autobuild uses a variables file to manage build configurations.

• Clone the Build Variables Repository:
  • Open Windows Command Prompt and navigate to your desired base directory (e.g., C:\firestorm).
  • Clone the Firestorm build variables repository: git clone https://github.com/FirestormViewer/fs-build-variables.git <path-to-your-variables-file>
    • Replace <path-to-your-variables-file> with a directory name of your choice, for example, fs-variables. Example command: git clone https://github.com/FirestormViewer/fs-build-variables.git fs-variables
• Set Environment Variable AUTOBUILD_VARIABLES_FILE:
  • Set the environment variable AUTOBUILD_VARIABLES_FILE to point to the variables file within the cloned repository. For example, if you cloned to C:\firestorm\fs-variables, set the variable to: C:\firestorm\fs-variables\variables

• Start Visual Studio 2022.
• Go to Tools > Options > Projects and Solutions > Build and Run.
• Set "maximum number of parallel projects builds" to 1.
  • This setting can sometimes improve build stability, especially on systems with many processor cores.

Plan your directory structure. Consider creating a base directory (e.g., C:\aperture-viewer-build) to organize your source code and build files.

• Clone the Aperture Viewer Source Code:
  • Open Windows Command Prompt and navigate to your base directory (e.g., C:\aperture-viewer-build).
  • Clone your Aperture Viewer repository from GitHub. For example, if your repository URL is https://github.com/williamweaver/Aperture-Viewer.git: git clone https://github.com/williamweaver/Aperture-Viewer.git
    • This will create a folder named Aperture-Viewer (or whatever your repository name is) containing the source code.

Most third-party libraries will be automatically downloaded during the build process. However, FMOD Studio requires manual preparation if you want to include it.

If you want to include FMOD Studio audio support in Aperture Viewer:

1. Download FMOD Studio API:

   • Download the FMOD Studio API (not the FMOD Studio Tool) from the FMOD website. You will need to create a free account to access the downloads.
   • Important: Make sure to download the FMOD Studio API and not the FMOD Studio Tool.

2. Clone the 3p-fmodstudio Repository:

   • Open Windows Command Prompt and navigate to your base directory (e.g., C:\aperture-viewer-build).
   • Clone the 3p-fmodstudio repository: git clone https://github.com/FirestormViewer/3p-fmodstudio.git

3. Place FMOD Studio Installer in Repository:

   • After cloning, copy the downloaded FMOD Studio installer file (e.g., fmodstudio_api_2.02.XX_windows.exe) into the root directory of the 3p-fmodstudio repository (C:\aperture-viewer-build\3p-fmodstudio).

4. Edit build-cmd.sh for Version Number:

   • Open the build-cmd.sh file located in C:\aperture-viewer-build\3p-fmodstudio in a text editor.
   • At the beginning of the file, you will find lines defining the FMOD Studio version. Modify these lines to match the version number of the FMOD Studio API installer you downloaded.

     FMOD_VERSION="20206"  # Example - replace with your version (short format, no separators)
     FMOD_VERSION_PRETTY="2.02.06" # Example - replace with your version (long format)

     • Example: If you downloaded FMOD Studio API version 2.02.06, you would set:

       FMOD_VERSION="20206"
       FMOD_VERSION_PRETTY="2.02.06"

5. 3p-fmodstudio/build-cmd.sh Line Ending Issues:

   Problem: The 3p-fmodstudio/build-cmd.sh script might sometimes have Windows (CRLF) line endings instead of Linux/Unix (LF) line endings. Since this script is executed in Cygwin/bash, CRLF line endings can cause build failures.

   Solution:

   • Convert Line Endings to LF:
     1. Install dos2unix in Cygwin: If you don't have it already, run the Cygwin installer (setup-x86_64.exe) again and select the dos2unix package in the "Utils" category to install it.
     2. Open a Cygwin terminal.
     3. Navigate to the 3p-fmodstudio directory: cd /cygdrive/c/aperture-viewer-build/3p-fmodstudio (adjust path if your base directory is different).
     4. Run the dos2unix command: dos2unix build-cmd.sh
     5. This will convert the line endings in build-cmd.sh to LF, which should resolve the issue.

6. Build and Package FMOD Studio with Autobuild:

   • Open Windows Command Prompt and navigate to the 3p-fmodstudio directory: cd C:\aperture-viewer-build\3p-fmodstudio
   • Run the following Autobuild commands:

     autobuild build -A 64 --all
     autobuild package -A 64 --results-file result.txt

     • During the autobuild build command, Windows may ask for permission to allow the FMOD Studio installer to make changes to your computer. Allow these changes.

7. Extract FMOD Studio Package Path and Hash:

   • After the autobuild package command completes, look at the output in the Command Prompt. Near the end, you will see a line indicating the package file path and name, for example:

     wrote  C:\aperture-viewer-build\3p-fmodstudio\fmodstudio-2.02.06-windows64-xxxxxxxxxx.tar.bz2
     

   • Also, a file named result.txt will be created in the 3p-fmodstudio directory. This file contains the MD5 hash value of the package file. Note down both the package file path and the MD5 hash value from result.txt.

8. Copy autobuild.xml and Set AUTOBUILD_CONFIG_FILE:

   • Navigate to your Aperture Viewer source code directory (e.g., C:\aperture-viewer-build\Aperture-Viewer).
   • Copy the autobuild.xml file and rename the copy to my_autobuild.xml.
   • Set the environment variable AUTOBUILD_CONFIG_FILE to point to this copied file: set AUTOBUILD_CONFIG_FILE=my_autobuild.xml

9. Edit my_autobuild.xml to Register FMOD Studio:

   • Open my_autobuild.xml in a text editor.

   • Locate the <installables> section.

   • Add the following <installable> entry within the <installables> section, replacing the placeholders with the actual FMOD Studio package path and MD5 hash value you noted down in step 7:

     <installable name="fmodstudio">
       <platform name="windows64">
         <archive name="fmodstudio-{version#}-windows64-{build_id}.tar.bz2"
                  hash="<md5 hash value from result.txt>"
                  url="file:///<FMOD Studio package path>" />
       </platform>
     </installable>

     • Example (replace with your actual values):

       <installable name="fmodstudio">
         <platform name="windows64">
           <archive name="fmodstudio-2.02.06-windows64-xxxxxxxxxx.tar.bz2"
                    hash="1234567890abcdef1234567890abcdef"  <!-- Replace with your actual MD5 hash -->
                    url="file:///C:/aperture-viewer-build/3p-fmodstudio/fmodstudio-2.02.06-windows64-xxxxxxxxxx.tar.bz2" /> <!-- Replace with your actual path -->
         </platform>
       </installable>

     • Important: Ensure the url path uses forward slashes (/) and that the drive letter is capitalized (e.g., file:///C:/...).

Open the Windows Command Prompt.

If you are building with FMOD Studio and are using a new Command Prompt window, ensure you reset the AUTOBUILD_CONFIG_FILE environment variable:

set AUTOBUILD_CONFIG_FILE=my_autobuild.xml

Then, navigate to your Aperture Viewer source code directory:

cd C:\aperture-viewer-build\Aperture-Viewer (or your actual directory)

Run the Autobuild configure command:

autobuild configure -A 64 -c ReleaseFS_open

This command configures Aperture Viewer with default settings and without certain third-party libraries (as specified by ReleaseFS_open).

Available Pre-Made Firestorm-Specific Build Targets (Configuration Presets):

• ReleaseFS: Includes KDU (Kakadu JPEG2000 library) and FMOD Studio audio.
• ReleaseFS_open: Excludes KDU and FMOD Studio (open-source configuration).
• RelWithDebInfoFS_open: Release build with debug information, excludes KDU and FMOD Studio.

You can use various switches to customize the configuration process. Each switch is followed by its type and the desired value.

• -A <architecture>: Sets the target architecture. Use -A 64 for 64-bit builds (default if omitted is 32-bit, but 32-bit is no longer supported for Aperture Viewer).

• --fmodstudio: Controls whether the FMOD Studio package is included. Requires completing the FMOD Studio setup steps in FMOD Studio Setup (Optional - If You Want FMOD Audio).

• --package: Ensures all necessary files are copied to the viewer output directory. Enable this switch if you want to be able to run the compiled viewer directly without building from Visual Studio.

• --chan <channel name>: Defines a custom channel name for the viewer (e.g., --chan MyAperture). This will affect the viewer's name displayed in Second Life.

• -DLL_TESTS:BOOL=<bool>: Controls whether unit tests are compiled and run. Excluding tests (-DLL_TESTS:BOOL=FALSE) is generally recommended unless you need to run or debug specific tests.

  [!TIP] OFF and NO are equivalent to FALSE; any other value is treated as TRUE.

Configuration Examples:

• Build a 64-bit viewer with FMOD Studio and create an installer package (NSIS required):

  autobuild configure -A 64 -c ReleaseFS_open -- --fmodstudio --package --chan MyAperture -DLL_TESTS:BOOL=FALSE

• Build a 64-bit viewer without FMOD Studio and without an installer package:

  autobuild configure -A 64 -c ReleaseFS_open -- --chan MyAperture -DLL_TESTS:BOOL=FALSE

You can build Aperture Viewer either from the Windows command line or within Visual Studio.

If building with FMOD Studio and using a new Command Prompt window, reset the AUTOBUILD_CONFIG_FILE environment variable:

set AUTOBUILD_CONFIG_FILE=my_autobuild.xml

Then, run the Autobuild build command, ensuring you use the same architecture parameter as during configuration:

autobuild build -A 64 -c ReleaseFS_open --no-configure

Compilation will take a significant amount of time depending on your system.

After configuration, a Visual Studio solution file (Firestorm.sln) will be created in the build-vc170-64 folder within your Aperture Viewer source directory (assuming you configured for 64-bit).

1. Open the Solution in Visual Studio:

   • Navigate to the build-vc170-64 folder (e.g., C:\aperture-viewer-build\Aperture-Viewer\build-vc170-64).
   • Double-click Firestorm.sln to open the Aperture Viewer solution in Visual Studio 2022.

2. Build the Solution:

   • In Visual Studio, go to the Build menu and select "Build Solution".
   • Wait for the build process to complete. The build progress will be displayed in the Visual Studio Output window.

If you encounter an error like this when running autobuild build:

../build.cmd.sh line 200: SystemRootsystem32: unbound variable

This is caused by the order of entries in your Windows "Path" environment variable. Autobuild exports Windows paths into Cygwin-style paths and variables. If Windows paths containing variables like %SystemRoot% are not in the correct order, this error can occur.

Solution:

• Check and Adjust Path Order: Ensure that the following system paths are listed early in your Windows "Path" environment variable and in the correct order:

  %SystemRoot%
  %SystemRoot%\system32
  %SystemRoot%\System32\Wbem
  

  You can edit your environment variables in the Windows System settings.