build/docs/visualstudio.rst@6474c204b198 (annotated)
build/docs/visualstudio.rst
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
| michael@0 | 1 | .. _build_visualstudio: |
| michael@0 | 2 | |
| michael@0 | 3 | ====================== |
| michael@0 | 4 | Visual Studio Projects |
| michael@0 | 5 | ====================== |
| michael@0 | 6 | |
| michael@0 | 7 | The build system contains alpha support for generating Visual Studio |
| michael@0 | 8 | project files to aid with development. |
| michael@0 | 9 | |
| michael@0 | 10 | To generate Visual Studio project files, you'll need to have a configured tree:: |
| michael@0 | 11 | |
| michael@0 | 12 | mach configure |
| michael@0 | 13 | |
| michael@0 | 14 | (If you have built recently, your tree is already configured.) |
| michael@0 | 15 | |
| michael@0 | 16 | Then, simply generate the Visual Studio build backend:: |
| michael@0 | 17 | |
| michael@0 | 18 | mach build-backend -b VisualStudio |
| michael@0 | 19 | |
| michael@0 | 20 | If all goes well, the path to the generated Solution (``.sln``) file should be |
| michael@0 | 21 | printed. You should be able to open that solution with Visual Studio 2010 or |
| michael@0 | 22 | newer. |
| michael@0 | 23 | |
| michael@0 | 24 | Currently, output is hard-coded to the Visual Studio 2010 format. If you open |
| michael@0 | 25 | the solution in a newer Visual Studio release, you will be prompted to upgrade |
| michael@0 | 26 | projects. Simply click through the wizard to do that. |
| michael@0 | 27 | |
| michael@0 | 28 | Structure of Solution |
| michael@0 | 29 | ===================== |
| michael@0 | 30 | |
| michael@0 | 31 | The Visual Studio solution consists of hundreds of projects spanning thousands |
| michael@0 | 32 | of files. To help with organization, the solution is divided into the following |
| michael@0 | 33 | trees/folders: |
| michael@0 | 34 | |
| michael@0 | 35 | Build Targets |
| michael@0 | 36 | This folder contains common build targets. The *full* project is used to |
| michael@0 | 37 | perform a full build. The *binaries* project is used to build just binaries. |
| michael@0 | 38 | The *visual-studio* project can be built to regenerate the Visual Studio |
| michael@0 | 39 | project files. |
| michael@0 | 40 | |
| michael@0 | 41 | Performing the *clean* action on any of these targets will clean the |
| michael@0 | 42 | *entire* build output. |
| michael@0 | 43 | |
| michael@0 | 44 | Binaries |
| michael@0 | 45 | This folder contains common binaries that can be executed from within |
| michael@0 | 46 | Visual Studio. If you are building the Firefox desktop application, |
| michael@0 | 47 | the *firefox* project will launch firefox.exe. You probably want one of |
| michael@0 | 48 | these set to your startup project. |
| michael@0 | 49 | |
| michael@0 | 50 | Libraries |
| michael@0 | 51 | This folder contains entries for each static library that is produced as |
| michael@0 | 52 | part of the build. These roughly correspond to each directory in the tree |
| michael@0 | 53 | containing C/C++. e.g. code from ``dom/base`` will be contained in the |
| michael@0 | 54 | ``dom_base`` project. |
| michael@0 | 55 | |
| michael@0 | 56 | These projects don't do anything when built. If you build a project here, |
| michael@0 | 57 | the *binaries* build target project is built. |
| michael@0 | 58 | |
| michael@0 | 59 | Updating Project Files |
| michael@0 | 60 | ====================== |
| michael@0 | 61 | |
| michael@0 | 62 | As you pull and update the source tree, your Visual Studio files may fall out |
| michael@0 | 63 | of sync with the build configuration. The tree should still build fine from |
| michael@0 | 64 | within Visual Studio. But source files may be missing and IntelliSense may not |
| michael@0 | 65 | have the proper build configuration. |
| michael@0 | 66 | |
| michael@0 | 67 | To account for this, you'll want to periodically regenerate the Visual Studio |
| michael@0 | 68 | project files. You can do this within Visual Studio by building the |
| michael@0 | 69 | ``Build Targets :: visual-studio`` project or by running |
| michael@0 | 70 | ``mach build-backend -b VisualStudio`` from the command line. |
| michael@0 | 71 | |
| michael@0 | 72 | Currently, regeneration rewrites the original project files. **If you've made |
| michael@0 | 73 | any customizations to the solution or projects, they will likely get |
| michael@0 | 74 | overwritten.** We would like to improve this user experience in the |
| michael@0 | 75 | future. |
| michael@0 | 76 | |
| michael@0 | 77 | Moving Project Files Around |
| michael@0 | 78 | =========================== |
| michael@0 | 79 | |
| michael@0 | 80 | The produced Visual Studio solution and project files should be portable. |
| michael@0 | 81 | If you want to move them to a non-default directory, they should continue |
| michael@0 | 82 | to work from wherever they are. If they don't, please file a bug. |
| michael@0 | 83 | |
| michael@0 | 84 | Invoking mach through Visual Studio |
| michael@0 | 85 | =================================== |
| michael@0 | 86 | |
| michael@0 | 87 | It's possible to build the tree via Visual Studio. There is some light magic |
| michael@0 | 88 | involved here. |
| michael@0 | 89 | |
| michael@0 | 90 | Alongside the Visual Studio project files is a batch script named ``mach.bat``. |
| michael@0 | 91 | This batch script sets the environment variables present in your *MozillaBuild* |
| michael@0 | 92 | development environment at the time of Visual Studio project generation |
| michael@0 | 93 | and invokes *mach* inside an msys shell with the arguments specified to the |
| michael@0 | 94 | batch script. This script essentially allows you to invoke mach commands |
| michael@0 | 95 | inside the MozillaBuild environment without having to load MozillaBuild. |
| michael@0 | 96 | |
| michael@0 | 97 | While projects currently only utilize the ``mach build`` command, the batch |
| michael@0 | 98 | script does not limit it's use: any mach command can be invoked. Developers |
| michael@0 | 99 | may abuse this fact to add custom projects and commands that invoke other |
| michael@0 | 100 | mach commands. |
