The Tor Browser: build/docs/visualstudio.rst@b8a032363ba2

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

     1 .. _build_visualstudio:

     3 ======================

     4 Visual Studio Projects

     5 ======================

     7 The build system contains alpha support for generating Visual Studio

     8 project files to aid with development.

    10 To generate Visual Studio project files, you'll need to have a configured tree::

    12    mach configure

    14 (If you have built recently, your tree is already configured.)

    16 Then, simply generate the Visual Studio build backend::

    18    mach build-backend -b VisualStudio

    20 If all goes well, the path to the generated Solution (``.sln``) file should be

    21 printed. You should be able to open that solution with Visual Studio 2010 or

    22 newer.

    24 Currently, output is hard-coded to the Visual Studio 2010 format. If you open

    25 the solution in a newer Visual Studio release, you will be prompted to upgrade

    26 projects. Simply click through the wizard to do that.

    28 Structure of Solution

    29 =====================

    31 The Visual Studio solution consists of hundreds of projects spanning thousands

    32 of files. To help with organization, the solution is divided into the following

    33 trees/folders:

    35 Build Targets

    36    This folder contains common build targets. The *full* project is used to

    37    perform a full build. The *binaries* project is used to build just binaries.

    38    The *visual-studio* project can be built to regenerate the Visual Studio

    39    project files.

    41    Performing the *clean* action on any of these targets will clean the

    42    *entire* build output.

    44 Binaries

    45    This folder contains common binaries that can be executed from within

    46    Visual Studio. If you are building the Firefox desktop application,

    47    the *firefox* project will launch firefox.exe. You probably want one of

    48    these set to your startup project.

    50 Libraries

    51    This folder contains entries for each static library that is produced as

    52    part of the build. These roughly correspond to each directory in the tree

    53    containing C/C++. e.g. code from ``dom/base`` will be contained in the

    54    ``dom_base`` project.

    56    These projects don't do anything when built. If you build a project here,

    57    the *binaries* build target project is built.

    59 Updating Project Files

    60 ======================

    62 As you pull and update the source tree, your Visual Studio files may fall out

    63 of sync with the build configuration. The tree should still build fine from

    64 within Visual Studio. But source files may be missing and IntelliSense may not

    65 have the proper build configuration.

    67 To account for this, you'll want to periodically regenerate the Visual Studio

    68 project files. You can do this within Visual Studio by building the

    69 ``Build Targets :: visual-studio`` project or by running

    70 ``mach build-backend -b VisualStudio`` from the command line.

    72 Currently, regeneration rewrites the original project files. **If you've made

    73 any customizations to the solution or projects, they will likely get

    74 overwritten.** We would like to improve this user experience in the

    75 future.

    77 Moving Project Files Around

    78 ===========================

    80 The produced Visual Studio solution and project files should be portable.

    81 If you want to move them to a non-default directory, they should continue

    82 to work from wherever they are. If they don't, please file a bug.

    84 Invoking mach through Visual Studio

    85 ===================================

    87 It's possible to build the tree via Visual Studio. There is some light magic

    88 involved here.

    90 Alongside the Visual Studio project files is a batch script named ``mach.bat``.

    91 This batch script sets the environment variables present in your *MozillaBuild*

    92 development environment at the time of Visual Studio project generation

    93 and invokes *mach* inside an msys shell with the arguments specified to the

    94 batch script. This script essentially allows you to invoke mach commands

    95 inside the MozillaBuild environment without having to load MozillaBuild.

    97 While projects currently only utilize the ``mach build`` command, the batch

    98 script does not limit it's use: any mach command can be invoked. Developers

    99 may abuse this fact to add custom projects and commands that invoke other

   100 mach commands.

The Tor Browser / file revision