Difference between revisions of "Viewer 2 Microsoft Windows Builds"

From Second Life Wiki
Jump to navigation Jump to search
(→‎Compiling the viewer with autobuild: Remove references to Fmod)
(→‎Post Configuration step: Add a note about .bat files, which really should be a Tip type)
Line 215: Line 215:
* Copy <code>\api\fmodexL.dll</code> to <code>\build-vc100\packages\lib\debug</code>
* Copy <code>\api\fmodexL.dll</code> to <code>\build-vc100\packages\lib\debug</code>
* Copy <code>\documentation\license.txt</code> to <code>build-vc100\packages\licenses\fmodex.txt</code>
* Copy <code>\documentation\license.txt</code> to <code>build-vc100\packages\licenses\fmodex.txt</code>
{{KBnote|The configuration and copy commands are long.  You may want to make two .bat files to simplify this process.  The first .bat file will perform the configure step.  The second .bat file will perform the copy step.  The reason to have two .bat files and not just one is the configure step will exit with an expected error.}}


== Compiling the Viewer ==
== Compiling the Viewer ==

Revision as of 13:56, 26 February 2014

Philosophy: to keep it brief, this page should only include steps we KNOW ARE NEEDED, not random hints. Extra details or open issues can go on the talk page.

KBnote.png Note: Following this recipe will probably take 6 to 12 hours of wall-clock time, and 2 to 6 hours of your time, if you're starting from a fresh Windows XP/Vista/7 system.
KBcaution.png Important: If you want to alter the build instructions please try to have a discussion with at least one person on #opensl on Freenode. There are language and stylistic conventions we try to follow and we want to make sure any change to these instructions is tested in a number of build environments before being published here.
Open Source Portal

Establish your programming environment

This is needed for compiling any viewer based on the LL open source code and only needs to be done once.

Install and update Visual Studio and SDKs

Install required development tools

KBnote.png Note: The order of the following installations should not matter.
KBnote.png Note: If the installer for a particular package does not update your PATH environment variable you will have to do this manually.
  • CMake (download CMake)
    • This should be version 2.8.8 (or above in the 2.8.x series).
    • Add the \bin directory to your path.
  • Python (either Standard Python or ActivePython)
    • Version 2.7.1 works with the build scripts.
  • Mercurial (either TortoiseHg or Mercurial Hg)
    • Create a new file %USERPROFILE%\Mercurial.ini and in it put your Second Life name and optionally your email address:
[ui]
username = John Doe <john@example.com>
  • Cygwin (download Cygwin)
    • When you run the cygwin setup utility make sure you have selected to install unzip (under "Archives"), bison, flex, patchutils (all located under "devel"), curl (under "Web"), and m4 (under "interpreters"). Do not install Cygwin Python or Mercurial. You won't need to use the Cygwin shell for anything.
    • Add the cygwin\bin directory to the very end of your path and make sure it stays that way.

Install optional development tools

  • Unicode NSIS (Nullsoft Scriptable Install System)
    • This is the package installer used to build Second_Life_<version-code>_LindenDeveloper_Setup.exe. You only need this package if you are going to distribute the viewer you compile or if you want to install it locally.
    In the Configure VS2010 step below you will need to add a line in the Executable Directories section:
    • 64 bit systems use %ProgramFiles(x86)%\NSIS\Unicode
    • 32 bit systems use %ProgramFiles%\NSIS\Unicode
  • Notepad++
  • Mercurial_Tools (strongly recommended)
    • When you are following these instructions you will be updating the %USERPROFILE%\Mercurial.ini file you created when you installed Mercurial.
  • FMOD Ex Api
    • This is the software that supports sounds. Installing it is optional but the installation instructions will assume you have installed it.

Install Autobuild

  • Add an environment variable, so that autobuild doesn't default to using (or trying) older compiler versions:
    • Right-click "My Computer" and select Properties or press the windows logo key and the pause key at the same time.
    • For XP, when the Properties dialog opens, click the Advanced tab followed by the Environmental Variables button. This will open a new window with a list of System and User variables. For Vista and later, when the System Properties window opens, click the Advanced system settings on the left column, then click Environment Variables...
    • In the User section, click New. Set Variable Name to AUTOBUILD_VSVER and set Variable Value to 100.
    • Click the OK/Close buttons to close all the windows.

Configure VC2010

While you may choose to use autobuild for all your compiling you still need to establish certain settings internal to VC2010.

  • Start the IDE.
  • Navigate to Tools > Options > Projects and Solutions > Build and Run and set maximum number of parallel projects builds to 1.
  • (VC Express only) Enable Tools > Settings > Expert Settings to get the Build (and other) menus. If you already have a Build menu you do not need to perform this step.
KBnote.png Note: The following steps require an open visual studio project. It does not matter which project you use, as you will only change some global settings used by all projects when they are opened. The open project itself won't be changed.

You will need to set a number of paths.

  • Open any existing project you may have or make a New Project.
  • Navigate to View ( > Other Windows ) > Property Manager. You will see Property Manager as a pane on the left side.

At the bottom on the Solution Explorer you will see three tabs.

  • Click the one on the right labeled Property Manager. (The name may be somewhat truncated.)

VS2010 Property Manager.PNG Example image

  • On the left side click to expand any project and then click again to expand the Release folder.

VS2010 Project Config.PNG Example image

  • Right click on Microsoft.Cpp.Win32.user and select Properties.
  • Pick General

Set Enable Managed Incremental Build to Yes.

  • Pick VC++ Directories.

This is where the build environment is pulled together into a functional VC2010 build system and also where much hand wringing, hair pulling, and fist pounding frustration takes place.

  • Set Executable Directories to:
$(ExecutablePath)
$(DXSDK_DIR)
$(WindowsSdkDir)\Bin
C:\cygwin\bin
$(SystemRoot)

32BitExecutableDirectories.png 32 bit Executable Directories example image

  • Set Include Directories to:
$(WindowsSdkDir)\Include
$(WindowsSdkDir)\Include\gl
$(DXSDK_DIR)\Include

32BitIncludeDirectories.png 32 bit Include Directories example image

  • Set Library Directories to:
$(WindowsSdkDir)\Lib
$(DXSDK_DIR)

32BitLibraryDirectories.png 32 bit Library Directories example image

Set up your source code tree

Plan your directory structure ahead of time. If you are going to be producing changes or patches you will be cloning a copy of an unaltered source code tree for every change or patch you make, so you might want to have all this work stored in it's own directory.

To get a copy of the source code tree:

  • Open up a DOS Command window
  • CD to where you want to install viewer-release. Do not have any spaces in this path.
  • Do:
hg clone http://hg.secondlife.com/viewer-release

Let's say some time has gone by since you have performed the previous steps and now you want to develop a change or work on a jira. You will update your clean local repository with all the changes committed to viewer-release since you last synchronized your files:

  • CD into viewer-release
  • Do:
hg pull -u
  • Move up one level from viewer-release
  • Do:
hg clone viewer-release VWR-nnnnn

Note: nnnnn is the jira number. You can also clone to a name of your choosing if you are making changes not associated with the LL jira system.

Configuring the Viewer Build

The basic command to configure the viewer build is 

autobuild configure [-c configuration type]

where configuration type is one of:

DebugOS
maximum debugging information - probably not best for regular use
ReleaseOS
maximum optimizations and some debugging features disabled - best performance
RelWithDebInfoOS
a compromise between the above two extremes - probably best for development

If you need to modify the autobuild.xml configuration file in a way that you don't want to commit, such as having added a locally built library package you will need to override the default configuration file by adding 

--config-file my_autobuild.xml

where my_autobuild.xml is the name of your local configuration file.

Configuration Switches

There are a number of switches you can specify to be passed through autobuild configure to the cmake command that creates your VS project files. These switches are added after the special argument "--". The name of each switch is followed by its type and then by the value you want to set. 

autobuild configure -- -Dswitch_name:switch_type=switch_value
FMODEX (bool)
Controls if the FmodEX package is incorporated into the viewer.
FMODEX_LIBRARY (path)
Specifies the location of the FmodEX .lib file needed for linking.
FMODEX_INCLUDE_DIR (path)
Specifies the location of the FmodEX include files.
LL_TESTS (bool)
Controls whether or not the unit and integration tests are compiled and run. There are quite a lot of them so excluding them does save some time building, but they may detect errors that will be hard to diagnose in a full viewer. If you plan to submit changes to Linden Lab, please ensure that you have run the tests before submitting.
PACKAGE (bool)
Controls whether or not the package step is run. The package step creates an installer for your viewer. You must have installed NSIS described in Viewer_2_Microsoft_Windows_Builds#Install_optional_development_tools for this to work.
VIEWER_CHANNEL
Sets the channel name for your viewer. See Channel and Version Requirements for how the channel name should be chosen and used.
Quoting for string values can be tricky, especially with multiple-word values; note the combination of single and double quotes:
autobuild configure -- -DVIEWER_CHANNEL:STRING='"channel"'
or use escaped double quotes:
autobuild configure -- -DVIEWER_CHANNEL:STRING="\"channel\""
KBnote.png Note: OFF and NO are the same as FALSE; anything else is considered to be TRUE.

Autobuild Cache Directory

In the course of building, autobuild will download and cache a fairly large number of prepackaged builds for components it needs. Most of these will not require that you change them, and autobuild will cache them so that it does not need to download them again.

The environment variable AUTOBUILD_INSTALLABLE_CACHE controls the location of the autobuild download cache directory. If you do not want the library files downloaded as part of the configure process going into your Windows %TEMP% directory define the environment variable to point to some other location you have established: 

set AUTOBUILD_INSTALLABLE_CACHE=E:\SSfiles\Libraries

Example configuration command

KBnote.png Note: You will need to adjust the configure command below to reflect where you have installed FmodEX. 
autobuild configure -c ReleaseOS -- -DPACKAGE:BOOL=OFF -DFMODEX:BOOL=TRUE -DFMODEX_LIBRARY:PATH=E:\FmodEX\api\fmodex_vc.lib -DFMODEX_INCLUDE_DIR:PATH=E:\FmodEX\api\inc

Post Configuration step

You need to copy three files from the FmodEX directory tree into the build tree that the configure command has just created.

  • Copy \api\fmodex.dll to \build-vc100\packages\lib\release
  • Copy \api\fmodexL.dll to \build-vc100\packages\lib\debug
  • Copy \documentation\license.txt to build-vc100\packages\licenses\fmodex.txt
KBnote.png Note: The configuration and copy commands are long. You may want to make two .bat files to simplify this process. The first .bat file will perform the configure step. The second .bat file will perform the copy step. The reason to have two .bat files and not just one is the configure step will exit with an expected error.

Compiling the Viewer

KBnote.png Note: Do not be alarmed if you see groups of messages with warning LNK4099: PDB in them.

Compiling the viewer with autobuild

You can compile the viewer with either autobuild (the encouraged/supported method) or with the VS IDE.

When compiling with autobuild you will have the best chance of success if you work from within a preconfigured Command Prompt window. Depending on how your computer has been set up there are two possible ways to open this window and you need to find which works in your particular case:

  • Method 1
    • From All Programs Navigate into the Microsoft Visual Studio 2010 program menu
    • Click on Microsoft Visual Studio Command Prompt (2010)
  • Method 2
    • From All Programs Navigate into the Microsoft Windows SDK V7.1 program menu
    • Click on Windows SDK 7.1 Command Prompt
  • Run:
autobuild build -c [CONFIGURATION] --no-configure

Example: 

autobuild build -c ReleaseOS --no-configure
KBnote.png Note: It is possible to use autobuild to do both the configure step (only needed once) and the build step with one command. I find it is clearer and saves a bit of time if these steps are done separately.

Compiling the viewer with the IDE

The autobuild configure step created the \build-vc100 directory at the root of the source tree. In here is the SecondLife.sln solution file.

Start the IDE and open this solution.

You might want to change the build type in the drop-down located in the toolbar from Debug to Release or RelWithDebInfo.

VS2010BuildType.png Changing build type example image

You need to adjust the Platform Toolset setting.

  • Select all the projects in the Solution Explorer list on the left of the screen.
    • Click on the first project and scroll to the bottom of this list and Shift ⇧-click on the last project.
  • Right click on the selected list
  • Navigate to Properties > Configuration Properties > General > Platform Toolset
  • Change this value to Windows7.1SDK
  • Push F7 to start the compiler.

Running your newly built viewer

Running from a desktop shortcut

  • Make a desktop shortcut for Drive:\your-path\build-vc100\newview\Release\secondlife-bin.exe
  • Right-click the shortcut
  • Select Properties
  • Set Start in: to Drive:\your-path\indra\newview

Running from within the IDE

  • In the Solution Explorer pane right click on secondlife-bin
    • Click Set as StartUp Project
    • Pick Properties > Configuration Properties > Debugging
      • Set Command to Drive:\your-path\build-vc100\newview\Release\secondlife-bin.exe (adjust Release to the type of build you are doing, e.g. RelWithDebInfo)
      • Set Working Directory to ..\..\indra\newview

Handling Problems

If you encounter errors or run into problems following the instructions above, please first check whether someone else already had the same issue. A solution might be known already. See the issue list below, check the talk page (and report useful experiences there) and search our issue tracker. Even when no description of your problem has been written down yet, someone might know about it, so get in touch with the community to get help.

Getting help

Common Issues/Bugs/Glitches And Solutions

A full build happens for NVIDIA users, when an incremental compile is expected

If you notice that you are suffering from full compiles when you should only be performing an incremental compile, you may be affected by jira issue OPEN-166. To fix this, see the instructions in Dolphin Linden's comment.

Not being able to find objidl.h in the Microsoft Windows SDK, when compiling llwindow

https://lists.secondlife.com/pipermail/opensource-dev/2011-April/006562.html

  • Can be caused by path problems or some installation conflicts with the DirectX SDK.

stdint.h typedef conflicts between Quicktime and VS2010

https://lists.secondlife.com/pipermail/opensource-dev/2011-April/006565.html

  • Can be solved by some small edits to header files to make sure the two don't bash on each other.

Eliminate deprecated switches, messages, and use memory more efficiently

The VS2010 compiler uses a lot of memory while compiling the viewer. If you run out of memory you will start to page heavily and your compile time will become much longer. The /Zm1000 switch affects compiler memory usage.

You may see this message while compiling: 

use 'EHsc' instead of 'GX'

Here is how to free up some memory the compiler allocates and to eliminate these messages:

  • Edit \CMake 2.8\share\cmake-2.8\Modules\Platform\Windows-cl.cmake
  • Replace line 156 with:
 IF(MSVC10)
   SET(CMAKE_CXX_FLAGS_INIT "/DWIN32 /D_WINDOWS /W3 /EHsc /GR")
 ELSEIF(NOT MSVC10)
   SET(CMAKE_CXX_FLAGS_INIT "/DWIN32 /D_WINDOWS /W3 /Zm1000 /EHsc /GR")
 ENDIF(MSVC10)
  • Replace line 172 with:
 IF(MSVC10)
   SET(CMAKE_CXX_FLAGS_INIT "/DWIN32 /D_WINDOWS /W3 /EHsc /GR")
 ELSEIF(NOT MSVC10)
   SET(CMAKE_CXX_FLAGS_INIT "/DWIN32 /D_WINDOWS /W3 /Zm1000 /GX /GR")
 ENDIF(MSVC10)
  • Replace line 184 with:
 IF(MSVC10)
   SET(CMAKE_CXX_FLAGS_INIT "/DWIN32 /D_WINDOWS /W3 /EHsc /GR")
 ELSEIF(NOT MSVC10)
   SET(CMAKE_CXX_FLAGS_INIT "/DWIN32 /D_WINDOWS /W3 /Zm1000 /GX /GR")
 ENDIF(MSVC10)

References

Tip of the hat to Nicky_Perian for User:Nicky_Perian/Visual_Studio_10_Autobuild

Retrieved from "https://wiki.secondlife.com/w/index.php?title=Viewer_2_Microsoft_Windows_Builds&oldid=1187923"