Difference between revisions of "Build the Viewer on macOS"

From Second Life Wiki
Jump to navigation Jump to search
(Xcode command line tools have been installed by default since 6.1, updated prereqs and made them less pedantic. Noted homebrew is an option, moved proprietary lib instructions to the bottom since they just confuse new developers who think they're required)
Line 6: Line 6:
The package versions and bit-widths listed below have been carefully selected and tested. If you decide to install a different version of a given package (even a minor update), you are on your own (but feel free to share your results.}}
The package versions and bit-widths listed below have been carefully selected and tested. If you decide to install a different version of a given package (even a minor update), you are on your own (but feel free to share your results.}}


==Getting Development Tools==
==Prerequisites==


;OSX
* [https://apps.apple.com/us/app/xcode/id497799835?mt=12 Xcode]
:These instructions assume that you are running OSX 10.12
* [https://cmake.org/download/ CMake] version 3.8 or newer
;Xcode 8
* [https://git-scm.com/download/mac git]
:Download and install Xcode 8 from the Apple App Store
* [[Autobuild]]
:Install the developer command line tools by running the command <tt>xcode-select --install</tt>
:Accept the xcode license by running the command <tt>sudo xcodebuild -license</tt> ; this diplays the license: page to the end and type <tt>agree</tt>
;CMake
:Install CMake (at least version 3.8) from [http://www.cmake.org cmake.org]
:You will need to arrange for the cmake executable to be in your PATH.
:The executable is '<tt>/Applications/CMake.app/Contents/bin/cmake</tt>'. Add that directory to your PATH, or create a symlink to the cmake executable in some directory that's in your PATH
;Mercurial
:Install the current Mercurial from [http://mercurial.selenic.com/downloads Selenic]
::If you may be contributing code back to the viewer, install the [[Mercurial_Tools#Coding_Policy|Mercurial Coding Policy hooks]]
;Autobuild 1.1
:Install the new version of autobuild as described on [[Autobuild]]


==Downloading Source Code==
You can install git and CMake using [https://brew.sh/ Homebrew] or their official installers.


The canonical viewer repository is https://bitbucket.org/lindenlab/viewer-release
Note: Be sure that cmake is available on your system path


===Get the viewer-build-variables===
~/ $ which cmake
/usr/local/bin/cmake


See [[Building the Viewer with Autobuild#Select Build Variables]]
==Download Source Code==


==Installing Proprietary Libraries==
The canonical viewer repository is https://bitbucket.org/lindenlab/viewer-release


Some builds of the the Viewer depends on proprietary libraries (alternative open source libraries are also provided for developers who prefer or are not licensed to use the proprietary libraries).  Lindens do not distribute these libraries, so you will need to fetch and install these even if you download the libraries packages.  (This is due to licensing restrictions. Don't ask, Lindens already did, and can't get permission. So you do have to get them yourself.)
  git clone https://bitbucket.org/lindenlab/viewer.git


===FMOD Ex===
===Get the viewer-build-variables===


PIck somewhere to build your fmodex package:
See [[Building the Viewer with Autobuild#Select Build Variables]]


hg clone <nowiki>https://bitbucket.org/lindenlab/3p-fmodex</nowiki>
==Configure==
cd 3p-fmodex
autobuild build
autobuild package


If it works, it will produce a package archive file with a name like <tt>fmodex-4.44.31.201503051234-darwin-201503051234.tar.bz2</tt>
Be sure you have the following environment variables set before continuing:


CD to your viewer repository root; you can either just override the configured archive with a --local install:
  AUTOBUILD_ADDRSIZE=64
 
  AUTOBUILD_VARIABLES_FILE=<path to autobuild viewer variables>
  autobuild install --local ''path-to-your-fmodex-archive''
 
That will cause autobuild to ignore the configured value and use your local package archive; if you delete your build directory, you'll need to repeat the override command.
 
To reconfigure your autobuild configuration file to use that archive:
 
  autobuild installables edit fmodex url=file:///''path-to-your-fmodex-archive''
 
but be careful not to commit that change, since it will be useless to anyone who can't access the path you configured.
 
==Configuring==
 
===Configuring your build with Autobuild===


Configuring and building with autobuild works the same on all platforms.  Full instructions may be found at [[Build_Viewer_With_Autobuild]].
Configuring and building with autobuild works the same on all platforms.  Full instructions may be found at [[Build_Viewer_With_Autobuild]].
Example:


  autobuild configure -c RelWithDebInfoOS  
  autobuild configure -c RelWithDebInfoOS  


if you built your own fmodex as above, add <tt>-- -DFMODEX:BOOL=TRUE</tt>
==Build==


==Building==
===Option 1: Command Line Build===
 
===Command Line Build===


  autobuild build --no-configure
  autobuild build --no-configure
Line 79: Line 49:
you can omit the --no-configure option: if you do, autobuild will implicitly run the configuration step before building. That's harmless, it just takes some extra time, but be sure to include any configuration options such as that for fmodex above.
you can omit the --no-configure option: if you do, autobuild will implicitly run the configuration step before building. That's harmless, it just takes some extra time, but be sure to include any configuration options such as that for fmodex above.


===Building within Xcode===
===Option 2: Build Within Xcode===


Once you have run the <tt>autobuild configure</tt> step, the directory ''build-darwin-x86_64'' will have been created in the root of your source distribution.  Inside that directory you will find the ''SecondLife.xcodeproj'' project file which can be used with Xcode.  When opened it should be configured correctly to build, so just '''Build and Run'''.  If it prompts you to automatically create schemes, let it do so.
Once you have run the <tt>autobuild configure</tt> step, the directory ''build-darwin-x86_64'' will have been created in the root of your source distribution.  Inside that directory you will find the ''SecondLife.xcodeproj'' project file which can be used with Xcode.  When opened it should be configured correctly to build, so just '''Build and Run'''.  If it prompts you to automatically create schemes, let it do so.
Line 85: Line 55:
==Running your newly built viewer==
==Running your newly built viewer==


===Command Line===
===Option 1: Command Line===


To launch the viewer you build, from your source tree root directory, run:
To launch the viewer you build, from your source tree root directory, run:
Line 93: Line 63:
where ''configuration-type'' depends on your built configuration ("DebugOS", "ReleaseOS" or "RelWithDebInfoOS").
where ''configuration-type'' depends on your built configuration ("DebugOS", "ReleaseOS" or "RelWithDebInfoOS").


===Running within Xcode===
===Option 2: Running Within Xcode===


"secondlife-bin" scheme is what you look for.
"secondlife-bin" scheme is what you look for.
Line 99: Line 69:
When running from the XCode IDE be sure to go to '''Product''' &rarr; '''Scheme''' &rarr; '''Edit Scheme''' menu. Select the '''Run''' section and uncheck the box labeled "Allow debugging when using document Versions Browser" on the '''Options''' tab. ([https://lists.secondlife.com/pipermail/opensource-dev/2014-February/009784.html See this thread.])
When running from the XCode IDE be sure to go to '''Product''' &rarr; '''Scheme''' &rarr; '''Edit Scheme''' menu. Select the '''Run''' section and uncheck the box labeled "Allow debugging when using document Versions Browser" on the '''Options''' tab. ([https://lists.secondlife.com/pipermail/opensource-dev/2014-February/009784.html See this thread.])


===Using Finder===
===Option 3: Using Finder===


# Navigate to <tt>build-darwin-x86_64/newview/''configuration-type''</tt>.
# Navigate to <tt>build-darwin-x86_64/newview/''configuration-type''</tt>.
Line 105: Line 75:
:You can create and put the alias wherever you find convenient.
:You can create and put the alias wherever you find convenient.


==Running the Unit Tests==
==Running Unit Tests==


From Xcode, open the project ''build-darwin-x86_64/test/test.xcodeproj'' and select "test" for scheme and run. ''SecondLife.xcodeproj'' project also has "test" scheme.
From Xcode, open the project ''build-darwin-x86_64/test/test.xcodeproj'' and select "test" for scheme and run. ''SecondLife.xcodeproj'' project also has "test" scheme.
==Optional: Installing Proprietary Libraries==
Some builds of the the Viewer depends on proprietary libraries (alternative open source libraries are also provided for developers who prefer or are not licensed to use the proprietary libraries).  Lindens do not distribute these libraries, so you will need to fetch and install these even if you download the libraries packages.  (This is due to licensing restrictions.  Don't ask, Lindens already did, and can't get permission.  So you do have to get them yourself.)
===Optional: FMOD Ex===
Pick somewhere to build your fmodex package:
hg clone <nowiki>https://bitbucket.org/lindenlab/3p-fmodex</nowiki>
cd 3p-fmodex
autobuild build
autobuild package
If it works, it will produce a package archive file with a name like <tt>fmodex-4.44.31.201503051234-darwin-201503051234.tar.bz2</tt>
CD to your viewer repository root; you can either just override the configured archive with a --local install:
autobuild install --local ''path-to-your-fmodex-archive''
That will cause autobuild to ignore the configured value and use your local package archive; if you delete your build directory, you'll need to repeat the override command.
To reconfigure your autobuild configuration file to use that archive:
autobuild installables edit fmodex url=file:///''path-to-your-fmodex-archive''
but be careful not to commit that change, since it will be useless to anyone who can't access the path you configured.
Now, reconfigure your viewer build to use FMod instead of the open source OpenAL library:
cd viewer # Go back to viewer checkout directory
autobuild configure -c RelWithDebInfoOS -- -DFMODEX:BOOL=TRUE


==Handling Problems==
==Handling Problems==

Revision as of 14:04, 31 July 2021

KBcaution.png Attend Carefully The package versions and bit-widths listed below have been carefully selected and tested. If you decide to install a different version of a given package (even a minor update), you are on your own (but feel free to share your results.

Prerequisites

You can install git and CMake using Homebrew or their official installers.

Note: Be sure that cmake is available on your system path

~/ $ which cmake
/usr/local/bin/cmake

Download Source Code

The canonical viewer repository is https://bitbucket.org/lindenlab/viewer-release

git clone https://bitbucket.org/lindenlab/viewer.git

Get the viewer-build-variables

See Building the Viewer with Autobuild#Select Build Variables

Configure

Be sure you have the following environment variables set before continuing:

AUTOBUILD_ADDRSIZE=64
AUTOBUILD_VARIABLES_FILE=<path to autobuild viewer variables>

Configuring and building with autobuild works the same on all platforms. Full instructions may be found at Build_Viewer_With_Autobuild.

autobuild configure -c RelWithDebInfoOS 

Build

Option 1: Command Line Build

autobuild build --no-configure

you can omit the --no-configure option: if you do, autobuild will implicitly run the configuration step before building. That's harmless, it just takes some extra time, but be sure to include any configuration options such as that for fmodex above.

Option 2: Build Within Xcode

Once you have run the autobuild configure step, the directory build-darwin-x86_64 will have been created in the root of your source distribution. Inside that directory you will find the SecondLife.xcodeproj project file which can be used with Xcode. When opened it should be configured correctly to build, so just Build and Run. If it prompts you to automatically create schemes, let it do so.

Running your newly built viewer

Option 1: Command Line

To launch the viewer you build, from your source tree root directory, run:

 open build-darwin-x86_64/newview/configuration-type/Second\ Life.app

where configuration-type depends on your built configuration ("DebugOS", "ReleaseOS" or "RelWithDebInfoOS").

Option 2: Running Within Xcode

"secondlife-bin" scheme is what you look for.

When running from the XCode IDE be sure to go to ProductSchemeEdit Scheme menu. Select the Run section and uncheck the box labeled "Allow debugging when using document Versions Browser" on the Options tab. (See this thread.)

Option 3: Using Finder

  1. Navigate to build-darwin-x86_64/newview/configuration-type.
  2. Double click the application.
You can create and put the alias wherever you find convenient.

Running Unit Tests

From Xcode, open the project build-darwin-x86_64/test/test.xcodeproj and select "test" for scheme and run. SecondLife.xcodeproj project also has "test" scheme.

Optional: Installing Proprietary Libraries

Some builds of the the Viewer depends on proprietary libraries (alternative open source libraries are also provided for developers who prefer or are not licensed to use the proprietary libraries). Lindens do not distribute these libraries, so you will need to fetch and install these even if you download the libraries packages. (This is due to licensing restrictions. Don't ask, Lindens already did, and can't get permission. So you do have to get them yourself.)

Optional: FMOD Ex

Pick somewhere to build your fmodex package:

hg clone https://bitbucket.org/lindenlab/3p-fmodex
cd 3p-fmodex
autobuild build 
autobuild package

If it works, it will produce a package archive file with a name like fmodex-4.44.31.201503051234-darwin-201503051234.tar.bz2

CD to your viewer repository root; you can either just override the configured archive with a --local install:

autobuild install --local path-to-your-fmodex-archive

That will cause autobuild to ignore the configured value and use your local package archive; if you delete your build directory, you'll need to repeat the override command.

To reconfigure your autobuild configuration file to use that archive:

autobuild installables edit fmodex url=file:///path-to-your-fmodex-archive

but be careful not to commit that change, since it will be useless to anyone who can't access the path you configured.

Now, reconfigure your viewer build to use FMod instead of the open source OpenAL library:

cd viewer # Go back to viewer checkout directory
autobuild configure -c RelWithDebInfoOS -- -DFMODEX:BOOL=TRUE

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.

You may find the solution in any of these resources:

Getting Help

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.