The Tor Browser / file comparison
comparison: build/docs/visualstudio.rst
build/docs/visualstudio.rst
- branch
- TOR_BUG_9701
- changeset 8
- 97036ab72558
equal
deleted
inserted
replaced
| -1:000000000000 | 0:580123713c64 |
|---|---|
| 1 .. _build_visualstudio: | |
| 2 | |
| 3 ====================== | |
| 4 Visual Studio Projects | |
| 5 ====================== | |
| 6 | |
| 7 The build system contains alpha support for generating Visual Studio | |
| 8 project files to aid with development. | |
| 9 | |
| 10 To generate Visual Studio project files, you'll need to have a configured tree:: | |
| 11 | |
| 12 mach configure | |
| 13 | |
| 14 (If you have built recently, your tree is already configured.) | |
| 15 | |
| 16 Then, simply generate the Visual Studio build backend:: | |
| 17 | |
| 18 mach build-backend -b VisualStudio | |
| 19 | |
| 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. | |
| 23 | |
| 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. | |
| 27 | |
| 28 Structure of Solution | |
| 29 ===================== | |
| 30 | |
| 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: | |
| 34 | |
| 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. | |
| 40 | |
| 41 Performing the *clean* action on any of these targets will clean the | |
| 42 *entire* build output. | |
| 43 | |
| 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. | |
| 49 | |
| 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. | |
| 55 | |
| 56 These projects don't do anything when built. If you build a project here, | |
| 57 the *binaries* build target project is built. | |
| 58 | |
| 59 Updating Project Files | |
| 60 ====================== | |
| 61 | |
| 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. | |
| 66 | |
| 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. | |
| 71 | |
| 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. | |
| 76 | |
| 77 Moving Project Files Around | |
| 78 =========================== | |
| 79 | |
| 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. | |
| 83 | |
| 84 Invoking mach through Visual Studio | |
| 85 =================================== | |
| 86 | |
| 87 It's possible to build the tree via Visual Studio. There is some light magic | |
| 88 involved here. | |
| 89 | |
| 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. | |
| 96 | |
| 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. |
