Last updated 09-Jul-2024

---

Extended instructions, tips, and ‘gotchas’ on how to compile and build Firestorm, a third-party Open Source viewer for use with Second Life by Linden Lab.

Includes both Firestorm for Windows and also Firestorm for Ubuntu Linux.

First published in February 2014, and regularly updated ever since.

NOTE: This article assumes that you are a competent software developer who is comfortable with C++ build environments and command consoles. Most people will have no need to build their own version of Firestorm from the source code.

---

Back in September 2010 I wrote about the pain of compiling your own Viewer and of the efforts of my friends Mariana and Forestaurora to try to write tutorials on doing it. Fortunately, things have moved on enormously since then and now it is fairly easy to do a private build. A majority of the work is in setting up your build environment.

After encountering and solving a few “gotchas”, I have successfully built Firestorm under both Windows and Ubuntu linux (various versions for both).

I thought it was worth noting down the “gotchas” I encountered, which is what this article is about.  If it helps just one other person in short-cutting the issues I have had, then this article will have been worth writing.

Although this article is primarily about compiling Firestorm, it could prove useful for other third-party viewers too, although your mileage may vary.

Update: It’s worth noting that I originally wrote this page whilst the Firestorm build instructions were out of date and full of inaccuracies and omissions, and during that time this page was quite useful. However, now that they have been brought up to date my page is possibly a little less useful for Windows builds as the instructions are now very good and straightforward, however there is still some extra useful information here and I go into more detail on some things than the official build instructions do.

 

 

---

Setting up the build environment

This covers the sections in the Firestorm build instructions to do with setting up the build environment.

Setting up your build environment is something you only need to do once. I will cover Windows and then Linux.

Windows

The follow section applies only to Windows builds.

The Firestorm build instructions are currently very accurate and straightforward, and currently there are not many gotchas.

The notes in this section will take you up to the “Prepare third party libraries” part of the Firestorm build instructions. You should then stop, and read on below here before continuing.

Specifically, you should not do the bit on FModStudio until you have read my notes further down.

C++ Compiler

The build system now uses Microsoft Visual Studio 2022 (VC17), and the Firestorm build instructions have been updated to reflect this.

It is absolutely fine to use the Community Edition of Visual Studio 2022, since it specifically and explicitly allows you to use it free of charge for Open Source projects.
You can download it from https://visualstudio.microsoft.com/ (note: may require creating a free account)

CMake

You will need the very latest version of CMake since support for VC17 was added only fairly recently.

Cygwin

Do not install the GCC compiler, or make, or CMake. If you do then I have found that Firestorm won’t compile because it picks up Cygwin’s version of CMake rather than the one it needs, and they were not compatible with each other at the original time of writing. I don’t know if this has since been fixed.

Python and pip

Prior to v6.5.3

For builds prior to v6.5.3, Python 2.7 was in use, and the build instructions said to download get-pip.py from https://bootstrap.pypa.io/get-pip.py but that link is to a version that requires Python3.

Instead you should download it from https://bootstrap.pypa.io/2.7/get-pip.py as that is the version for Python 2.7

v6.5.3 onwards

You should just be able to follow the build instructions now.

 

Linux (Ubuntu)

There were several versions of the build instructions for compiling Firestorm under Linux. They were all subtly different, however it looks like they have now been standardised into one definitive page (at last!)

I used these build instructions and, as recommended, I initially used Ubuntu 18.04 LTS (64-bit) running as a Virtual Machine (VM) under VirtualBox.

I subsequently also did successful builds with Ubuntu 20.04 LTS on bare metal and 20.04 LTS under Windows Subsystem for Linux (WSL2)

As you can guess, this was a while ago now and I have not done a build since then.

The following headings refer to the equivalent headings in the Firestorm build instructions for Linux…

Create your source tree
No notes on this. You can just do this.

Install Required Packages

Prior to v6.5.3

For builds prior to v6.5.3, Python 2.7 was in use and you should omit “python-pip” as this will install an incorrect version of pip that does not have support for Python 2.7 and instead substitute it for “python” (so that python gets installed)

Now we download and install the correct version of pip

cd ~/src
wget https://bootstrap.pypa.io/pip/2.7/get-pip.py
sudo -H python get-pip.py

v6.5.3 onwards

You should just be able to follow the build instructions “as is”.

CMake
The Firestorm build instructions say to build CMake from source, but this takes ages. Instead you could get a pre-build binary by following the instructions at https://apt.kitware.com

Install Autobuild
You can do this section “as is”.

Download the Source Code
You can go ahead and do this, but before cloning FModStudio read on below, and then we’ll continue further on down.

 

---

Building the libraries

This applies to both Windows and Linux.

Most of the libraries that are required by a Viewer are pulled in automatically by autobuild, with the exception of FModStudio and KDU.

FModStudio is the library that the Viewers use to play sounds. If you don’t have this library linked in, your Viewer will behave as if you have muted all sounds. The build instructions detail how to build this library, but do not tell you how to link it in. I will shortly mention how.

KDU (Kakadu) is a library that is to do with rendering JPEG2000 images. Unlike FModStudio, the build instructions do not say how to build this, but there is a mention that if you want to use it you must license it yourself and build it yourself. Currently a personal non-commercial license is US$250 which rules it out for me. Fortunately you do not need it as without it the Viewer just uses the OpenJPEG library instead which, although not as fast as KDU, is free.

However, there are currently are some issues with OpenJPEG which give the “Andy Warhol effect”, and I am looking into how to resolve this. See https://community.secondlife.com/forums/topic/481953… for more info.

KDU

As mentioned above, it is not feasible to build KDU but it can be omitted.

FModStudio

FModStudio is supported in Firestorm v5.1.1 onwards. Older versions used FModEx, and I have now removed my notes on that (although you can find them via this link on the Wayback Machine).

You will need to go to the FMod website and login (you’ll need to create an account if you don’t already have one) and then you can download FModStudio from the download area. Be sure to download the FMOD Engine (a.k.a. the FMOD Studio API), not the FMOD Studio Tool.

Select the appropriate version from the droplist, and download the version appropriate for your operating system. For Windows, download the Windows version (not the Windows 10 UWP version).

Copy it to the 3p-fmodstudio directory that was created when you were following the build instructions.

Edit the file build-cmd.sh and change the 3rd line from

FMOD_DOWNLOAD_BASE="http://erebus/dev/pkg/"

to

FMOD_DOWNLOAD_BASE="http://localhost/dev/pkg/"

This is very important, as  otherwise the script will try to download the package from the internet, and will fail (possibly with  “curl: (7) Failed to connect to erebus” or “curl: (28) Connection timed out after 300305 milliseconds“, followed by “ERROR: building configuration“).

This is because erebus is a server local to the Firestorm team and is not accessible over the internet, whereas localhost tells the script to look on your local PC.

As mentioned in the build instructions, note down the “wrote” and “md5” output values as you will need them later.

 

---

Build parameters

The predefined build parameters are rather “all or nothing” approach. If you build with ReleaseFS then it tries to link both FMod and KDU, and fails because KDU is missing. If you build with ReleaseFS_open then it uses neither and you are left with a muted Viewer, and also lacking Havok support.

Since there is no build parameter for “do not use KDU” we compile with the ReleaseFS_open target (since this does not include KDU) and then use the build parameters to add back in what we want.

First we want to include FModStudio in order to get sound, so we include the switch --fmodstudio

Then, because doing an OpenSim build disables the Havok physics engine, we add --no-opensim to fix that.

For 64-bit builds we add -A 64

Finally, the build system lets you enable Advanced Vector Extensions (AVX), an explanation of which is beyond the scope of this article.

To enable AVX you add --avx to the configure command or for AVX2 you add --avx2 instead. The build will barf if you try to use both.

CAUTION:
Choose carefully whether or not to enable AVX or AVX2, because if you run the resulting build on a CPU that does not support it then it will crash on startup. Most modern CPUs do, however.

 

---

Performing a build

Windows

1. 1. Open a command window in the location of your source folder.Note: A standard Windows command prompt, not the VS2022 command prompt.
   2. Set up the VC17 build environment for 64-bit compilation, which I do with a batch file that executes the following commands

      pushd "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\"
      call vcvarsall amd64
      popd

      Note: This assumes that Visual Studio is installed on your c: drive. If you have it elsewhere then adjust as necessary. Also, the above commands must be executed in a batch file and not from the command line!

   3. Update autobuild.xml (or my_autobuild.xml if you are doing that) with the fmodstudio information.Note: You only need to do this the first time you do a build, or if you revert the file.
      (I use a batch file for this, which I show below).

      autobuild installables edit fmodstudio platform=windows64 hash=md5 url=file://wrote

      The values of md5 and wrote are the values output when you built FModStudio.

   4. Ensure that the AUTOBUILD_VSVER and AUTOBUILD_VARIABLES_FILE environment variables are set. If you get an error saying that these are not set even though they are, or that “load_vsvars” is missing, then make sure you have the latest Cygwin installed. After installing, ensure that your Cygwin bin folder still comes before %SystemRoot%\system32 in your path, as updating Cygwin can alter the order.Also, if you have only just set them (and set them via the GUI), you may need to close your command prompt and open a new one, as environment variables are copied when the command prompt is opened and don’t get updated.
   5. Execute the following command

      autobuild build -A 64 -c ReleaseFS_open -- --chan MY_CHANNEL --package --fmodstudio --no-opensim -DFS_UPGRADECODES='GUID1,GUID2' -DLL_TESTS:BOOL=FALSE

      (add in any other flags like --avx etc. that you wish, but read my caution on the use of --avx that I mentioned earlier)

      MY_CHANNEL is the name of your private build, eg. AwesomeSauce, which would result in a version of Firestorm that identifies itself as “Firestorm-AwesomeSauce”. If you omit this, it will use the name of your computer, prefixed by “private-“.
      Do not use spaces or punctuation!

      GUID1 and GUID2 are generated by, for example, the Visual Studio GUID Generator. Make sure to always use the same GUIDs per channel. They identify the installation for upgrades and installation.

      GUIDs should be in registry format, but without the curly braces, eg. FC4F6A13-04BF-4613-983A-0E6864FF44B0

      Note: You should use different GUIDs for GUID1 and GUID2

This should then build a 64-bit version of Firestorm for Windows that has sound.

You can either run the resulting executable directly for testing purposes, or else run the installer in order to install it properly.

NOTE:
I have a few batch files that I use, which make things more convenient for me.

Firstly I have a batch file that creates my_autobuild.xml for me.

update_autobuild.bat

@echo off
echo Copying autobuild.xml to my_autobuild.xml
copy autobuild.xml my_autobuild.xml /Y 
set AUTOBUILD_CONFIG_FILE=my_autobuild.xml
echo.
echo Updating FModStudio info...
echo.
setlocal EnableDelayedExpansion
pushd ..\3p-fmodstudio\
set "FMODSTUDIO_LOCATION=%CD%"
popd
set FMODSTUDIO_PLATFORM=windows64
set FMODSTUDIO_HASH=8c1f3bc12f8490272b71c9c5ce463931
set FMODSTUDIO_FILE=fmodstudio-2.02.09-windows64-222951310.tar.bz2
set "FMODSTUDIO_FILENAME=!%FMODSTUDIO_LOCATION%\%FMODSTUDIO_FILE%!"
echo Location: %FMODSTUDIO_LOCATION%
echo Platform: %FMODSTUDIO_PLATFORM%
echo Hash: %FMODSTUDIO_HASH%
echo File: %FMODSTUDIO_FILE%
autobuild installables edit fmodstudio platform=%FMODSTUDIO_PLATFORM% hash=%FMODSTUDIO_HASH% url=file:///%FMODSTUDIO_LOCATION%\%FMODSTUDIO_FILE%
endlocal

That copies the file, and then updates it with my FModStudio information that I mentioned earlier.

Then I have a batch file that does the configure step (I actually have several of these, that build with AVX, without AVX, and build ‘Release with debug info’ for debugging).

config_ReleaseFS_open_64-bit_NoAVX.bat

@echo off
set AUTOBUILD_CONFIG_FILE=my_autobuild.xml
call autobuild configure -A 64 -v -c ReleaseFS_open -- --chan Beccapet --package --fmodstudio --no-opensim -DFS_UPGRADECODES='********-****-****-****-************,********-****-****-****-************' -DLL_TESTS:BOOL=FALSE

(Note: my GUIDs have been obfuscated with ‘*’ characters. Obviously you would substitute this for your own GUIDs)

And finally a batch file that does the actual build. Doing it this way slightly speeds up doing iterative compilation as it allows you to cut out the configuration step when doing subsequent builds.

build_ReleaseFS_open_64-bit.bat

@echo off
set AUTOBUILD_CONFIG_FILE=my_autobuild.xml
call autobuild build -A 64 -v -c ReleaseFS_open --no-configure --verbose

Linux

1. Open a terminal window in the location of your source directory
2. Update autobuild.xml (or my_autobuild.xml if you are doing that) with the fmodstudio information.
   Note: You only need to do this the first time you do a build, or if you revert the file.

   autobuild installables edit fmodstudio platform=linux64 hash=md5 url=file:///wrote

   The values of md5 and wrote are the values output when you built FModStudio.

   So for example

   autobuild installables edit fmodstudio platform=linux64 hash=b304c25772ddfb546d750e765d503e6f url=file:////home/becca/src/3p-fmodstudio/fmodstudio-2.02.01-linux64-212001931.tar.bz2

   (Note the four slashes. The first three are for file:/// and then the fourth is the start of the path)

   Note: You need to specify an absolute path; relative paths don’t seem to work

3. Ensure that the autobuild variables are exported

   export AUTOBUILD_VARIABLES_FILE=$HOME/src/fs-build-variables/variables

4. Execute the following commands

   autobuild configure -A 64 -v -c ReleaseFS_open -- --chan="MY_CHANNEL" --package --fmodstudio --no-opensim -DLL_TESTS:BOOL=FALSE
   autobuild build -A 64 -v -c ReleaseFS_open --no-configure --verbose
   

   MY_CHANNEL is the name of your private build, eg. AwesomeSauce, which would result in a version of Firestorm that identifies itself as “Firestorm-AwesomeSauce”. If you omit this, it will use the name of your computer, prefixed by “private-“.
   Do not use spaces or punctuation!

This should then build a 64-bit version of Firestorm for Linux that has sound and targets Second Life (but not OpenSim).

As with the Windows version above, I have several shell scripts that speed things up for me.

update_autobuild.sh

#!/usr/bin/env bash
cp -f autobuild.xml my_autobuild.xml
export AUTOBUILD_CONFIG_FILE=my_autobuild.xml
autobuild installables edit fmodstudio platform=linux64 hash=0e8842ec2cf693fe023050d0b0441bd1 url=file:////home/becca/src/3p-fmodstudio/fmodstudio-2.02.01-linux64-212010127.tar.bz2

 

config_ReleaseFS_open_64-bit_NoAVX.sh

#!/usr/bin/env bash
export AUTOBUILD_VARIABLES_FILE=$HOME/src/fs-build-variables/variables
export AUTOBUILD_CONFIG_FILE=my_autobuild.xml
autobuild configure -A 64 -v -c ReleaseFS_open -- --chan Beccapet --package --fmodstudio --no-opensim -DLL_TESTS:BOOL=FALSE

 

build_ReleaseFS_open_64-bit.sh

#!/usr/bin/env bash
export AUTOBUILD_VARIABLES_FILE=$HOME/src/fs-build-variables/variables
export AUTOBUILD_CONFIG_FILE=my_autobuild.xml
autobuild build -A 64 -v -c ReleaseFS_open --no-configure --verbose

 

---

Building the release viewer instead

All of the above instructions are for building the latest “bleeding edge” developer code from the trunk of the repository. However, if you want to play it safe and build the latest release branch, then it is possible to do so.

In the past you needed a different URL, but since the move to git the release branch is an actual branch so just switch your local repo to that.

 

---

 

Summary

My build instructions result in a private build of Firestorm for Second Life that uses OpenJPEG but also links in FModStudio, giving a Firestorm that connects fine to Second Life and has sound. Exactly what I want. The lack of KDU doesn’t make it noticeably slower for me, although your mileage may vary.

Although the above looks a little daunting, most of the work is in setting up your build environment, and it’s not as bad as it looks.

One slightly annoying aspect of switching between the installed Firestorm and the private build one, is that it seems to clear my cache. That means that every time I switch between them, I rezz as a cloud and have to wait ages for my inventory to load. I haven’t found a way round this yet, although I’m sure one exists. In the meantime it’s something to be aware of.

Anyway, I hope that this post has been useful to someone.

 

---

Links and Further Reading

Get source and compile – Official Second Life Viewer build instructions from Linden Lab
Compiling Firestorm Viewer – a top-level page for all platforms
Firestorm Windows build instructions – build instructions tailored for Windows builds.
Firestorm Linux build instructions – build instructions tailored for Linux builds