OLD | NEW |
1 # Introduction | 1 # Linux Eclipse Dev |
2 | 2 |
3 Eclipse can be used on Linux (and probably Windows and Mac) as an IDE for develo
ping Chromium. It's unpolished, but here's what works: | 3 Eclipse can be used on Linux (and probably Windows and Mac) as an IDE for |
4 | 4 developing Chromium. It's unpolished, but here's what works: |
5 * Editing code works well (especially if you're used to it or Visual Studio). | 5 |
6 * Navigating around the code works well. There are multiple ways to do this (F
3, control-click, outlines). | 6 * Editing code works well (especially if you're used to it or Visual Studio). |
7 * Building works fairly well and it does a decent job of parsing errors so tha
t you can click and jump to the problem spot. | 7 * Navigating around the code works well. There are multiple ways to do this |
8 * Debugging is hit & miss. You can set breakpoints and view variables. STL con
tainers give it (and gdb) a bit of trouble. Also, the debugger can get into a ba
d state occasionally and eclipse will need to be restarted. | 8 (F3, control-click, outlines). |
9 * Refactoring seems to work in some instances, but be afraid of refactors that
touch a lot of files. | 9 * Building works fairly well and it does a decent job of parsing errors so |
10 | 10 that you can click and jump to the problem spot. |
11 # Setup | 11 * Debugging is hit & miss. You can set breakpoints and view variables. STL |
12 | 12 containers give it (and gdb) a bit of trouble. Also, the debugger can get |
13 ## Get & Configure Eclipse | 13 into a bad state occasionally and eclipse will need to be restarted. |
| 14 * Refactoring seems to work in some instances, but be afraid of refactors that |
| 15 touch a lot of files. |
| 16 |
| 17 [TOC] |
| 18 |
| 19 ## Setup |
| 20 |
| 21 ### Get & Configure Eclipse |
14 | 22 |
15 Eclipse 4.3 (Kepler) is known to work with Chromium for Linux. | 23 Eclipse 4.3 (Kepler) is known to work with Chromium for Linux. |
16 * Download the distribution appropriate for your OS. For example, for Linux 64
-bit/Java 64-bit, use the Linux 64 bit package from http://www.eclipse.org/downl
oads/ (Eclipse Packages Tab -> Linux 64 bit (link in bottom right)). | 24 |
17 * Tip: The packaged version of eclipse in distros may not work correctly wit
h the latest CDT plugin (installed below). Best to get them all from the same so
urce. | 25 * Download the distribution appropriate for your OS. For example, for Linux |
18 * Googlers: The version installed on Goobuntu works fine. The UI will be muc
h more responsive if you do not install the google3 plug-ins. Just uncheck all
the boxes at first launch. | 26 64-bit/Java 64-bit, use the Linux 64 bit package from |
19 * Unpack the distribution and edit the eclipse/eclipse.ini to increase the hea
p available to java. For instance: | 27 http://www.eclipse.org/downloads/ (Eclipse Packages Tab -> Linux 64 bit |
20 * Change -Xms40m to -Xms1024m (minimum heap) and -Xmx256m to -Xmx3072m (maxi
mum heap). | 28 (link in bottom right)). |
21 * Googlers: Edit ~/.eclipse/init.sh to add this: | 29 * Tip: The packaged version of eclipse in distros may not work correctly |
22 ``` | 30 with the latest CDT plugin (installed below). Best to get them all from |
23 export ECLIPSE_MEM_START="1024M" | 31 the same source. |
24 export ECLIPSE_MEM_MAX="3072M" | 32 * Googlers: The version installed on Goobuntu works fine. The UI will be |
25 ``` | 33 much more responsive if you do not install the google3 plug-ins. Just |
26 The large heap size prevents out of memory errors if you include many Chrome sub
projects that Eclipse is maintaining code indices for. | 34 uncheck all the boxes at first launch. |
27 * Turn off Hyperlink detection in the Eclipse preferences. (Window -> Preferen
ces, search for "Hyperlinking, and uncheck "Enable on demand hyperlink style nav
igation"). | 35 * Unpack the distribution and edit the eclipse/eclipse.ini to increase the |
28 | 36 heap available to java. For instance: |
29 Pressing the control key on (for keyboard shortcuts such as copy/paste) can trig
ger the hyperlink detector. This occurs on the UI thread and can result in the r
eading of jar files on the Eclipse classpath, which can tie up the editor due to
the size of the classpath in Chromium. | 37 * Change `-Xms40m` to `-Xms1024m` (minimum heap) and `-Xmx256m` to |
30 | 38 `-Xmx3072m` (maximum heap). |
31 ## A short word about paths | 39 * Googlers: Edit `~/.eclipse/init.sh` to add this: |
| 40 |
| 41 export ECLIPSE_MEM_START="1024M" |
| 42 export ECLIPSE_MEM_MAX="3072M" |
| 43 |
| 44 The large heap size prevents out of memory errors if you include many Chrome |
| 45 subprojects that Eclipse is maintaining code indices for. |
| 46 |
| 47 * Turn off Hyperlink detection in the Eclipse preferences. (Window -> |
| 48 Preferences, search for "Hyperlinking, and uncheck "Enable on demand |
| 49 hyperlink style navigation"). |
| 50 |
| 51 Pressing the control key on (for keyboard shortcuts such as copy/paste) can |
| 52 trigger the hyperlink detector. This occurs on the UI thread and can result in |
| 53 the reading of jar files on the Eclipse classpath, which can tie up the editor |
| 54 due to the size of the classpath in Chromium. |
| 55 |
| 56 ### A short word about paths |
32 | 57 |
33 Before you start setting up your work space - here are a few hints: | 58 Before you start setting up your work space - here are a few hints: |
34 * Don't put your checkout on a remote file system (e.g. NFS filer). It's too
slow both for building and for Eclipse. | 59 |
35 * Make sure there is no file system link in your source path because Ninja wil
l resolve it for a faster build and Eclipse / GDB will get confused. (Note: This
means that the source will possibly not reside in your user directory since it
would require a link from filer to your local repository.) | 60 * Don't put your checkout on a remote file system (e.g. NFS filer). It's too |
36 * You may want to start Eclipse from the source root. To do this you can add a
n icon to your task bar as launcher. It should point to a shell script which wil
l set the current path to your source base, and then start Eclipse. The result w
ould probably look like this: | 61 slow both for building and for Eclipse. |
37 ``` | 62 * Make sure there is no file system link in your source path because Ninja |
38 ~/.bashrc | 63 will resolve it for a faster build and Eclipse / GDB will get confused. |
39 cd /usr/local/google/chromium/src | 64 (Note: This means that the source will possibly not reside in your user |
40 export PATH=/home/skuhne/depot_tools:/usr/local/google/goma/goma:/opt/eclipse:/u
sr/local/symlinks:/usr/local/scripts:/usr/local/sbin:/usr/local/bin:/usr/sbin:/u
sr/bin:/sbin:/bin | 65 directory since it would require a link from filer to your local |
41 /opt/eclipse/eclipse -vm /usr/bin/java | 66 repository.) |
42 ``` | 67 * You may want to start Eclipse from the source root. To do this you can add |
43 | 68 an icon to your task bar as launcher. It should point to a shell script |
44 (Note: Things work fine for me without launching Eclipse from a special director
y. jamescook@chromium.org 2012-06-1) | 69 which will set the current path to your source base, and then start Eclipse. |
45 | 70 The result would probably look like this: |
46 ## Run Eclipse & Set your workspace | 71 |
47 | 72 ```shell |
48 Run eclipse/eclipse in a way that your regular build environment (export CC, CXX
, etc...) will be visible to the eclipse process. | 73 ~/.bashrc |
49 | 74 cd /usr/local/google/chromium/src |
50 Set the Workspace to be a directory on a local disk (e.g. /work/workspaces/chrom
e). Placing it on an NFS share is not recommended -- it's too slow and Eclipse
will block on access. Don't put the workspace in the same directory as your che
ckout. | 75 export PATH=/home/skuhne/depot_tools:/usr/local/google/goma/goma:/opt/eclips
e:/usr/local/symlinks:/usr/local/scripts:/usr/local/sbin:/usr/local/bin:/usr/sbi
n:/usr/bin:/sbin:/bin |
51 | 76 /opt/eclipse/eclipse -vm /usr/bin/java |
52 ## Install the C Development Tools ("CDT") | 77 ``` |
53 | 78 |
54 1. From the Help menu, select Install New Software... | 79 (Note: Things work fine for me without launching Eclipse from a special |
55 1. Select the URL for the CDT, http://download.eclipse.org/tools/cdt/release
s/kepler | 80 directory. jamescook@chromium.org 2012-06-1) |
56 1. If it's not there you can click Add... and add it. | 81 |
57 1. Googlers: We have a local mirror, but be sure you run prodaccess before t
rying to use it. | 82 ### Run Eclipse & Set your workspace |
58 1. Select & install the Main and Optional features. | 83 |
59 1. Restart Eclipse | 84 Run eclipse/eclipse in a way that your regular build environment (export CC, |
60 1. Go to Window > Open Perspective > Other... > C/C++ to switch to the C++ per
spective (window layout). | 85 CXX, etc...) will be visible to the eclipse process. |
61 1. Right-click on the "Java" perspective in the top-right corner and select "C
lose" to remove it. | 86 |
62 | 87 Set the Workspace to be a directory on a local disk (e.g. |
63 ## Create your project(s) | 88 `/work/workspaces/chrome`). Placing it on an NFS share is not recommended -- |
64 | 89 it's too slow and Eclipse will block on access. Don't put the workspace in the |
65 First, turn off automatic workspace refresh and automatic building, as Eclipse t
ries to do these too often and gets confused: | 90 same directory as your checkout. |
66 | 91 |
67 1. Open Window > Preferences | 92 ### Install the C Development Tools ("CDT") |
68 1. Search for "workspace" | 93 |
69 1. Turn off "Build automatically" | 94 1. From the Help menu, select Install New Software... |
70 1. Turn off "Refresh using native hooks or polling" | 95 1. Select the URL for the CDT, |
71 1. Click "Apply" | 96 http://download.eclipse.org/tools/cdt/releases/kepler |
| 97 1. If it's not there you can click Add... and add it. |
| 98 1. Googlers: We have a local mirror, but be sure you run prodaccess before |
| 99 trying to use it. |
| 100 1. Select & install the Main and Optional features. |
| 101 1. Restart Eclipse |
| 102 1. Go to Window > Open Perspective > Other... > C/C++ to switch to the C++ |
| 103 perspective (window layout). |
| 104 1. Right-click on the "Java" perspective in the top-right corner and select |
| 105 "Close" to remove it. |
| 106 |
| 107 ### Create your project(s) |
| 108 |
| 109 First, turn off automatic workspace refresh and automatic building, as Eclipse |
| 110 tries to do these too often and gets confused: |
| 111 |
| 112 1. Open Window > Preferences |
| 113 1. Search for "workspace" |
| 114 1. Turn off "Build automatically" |
| 115 1. Turn off "Refresh using native hooks or polling" |
| 116 1. Click "Apply" |
72 | 117 |
73 Create a single Eclipse project for everything: | 118 Create a single Eclipse project for everything: |
74 | 119 |
75 1. From the File menu, select New > Project... | 120 1. From the File menu, select New > Project... |
76 1. Select C/C++ Project > Makefile Project with Existing Code | 121 1. Select C/C++ Project > Makefile Project with Existing Code |
77 1. Name the project the exact name of the directory: "src" | 122 1. Name the project the exact name of the directory: "src" |
78 1. Provide a path to the code, like /work/chromium/src | 123 1. Provide a path to the code, like /work/chromium/src |
79 1. Select toolchain: Linux GCC | 124 1. Select toolchain: Linux GCC |
80 1. Click Finish. | 125 1. Click Finish. |
81 | 126 |
82 Chromium has a huge amount of code, enough that Eclipse can take a very long tim
e to perform operations like "go to definition" and "open resource". You need t
o set it up to operate on a subset of the code. | 127 Chromium has a huge amount of code, enough that Eclipse can take a very long |
| 128 time to perform operations like "go to definition" and "open resource". You need |
| 129 to set it up to operate on a subset of the code. |
83 | 130 |
84 In the Project Explorer on the left side: | 131 In the Project Explorer on the left side: |
85 | 132 |
86 1. Right-click on "src" and select "Properties..." | 133 1. Right-click on "src" and select "Properties..." |
87 1. Open Resource > Resource Filters | 134 1. Open Resource > Resource Filters |
88 1. Click "Add..." | 135 1. Click "Add..." |
89 1. Add the following filter: | 136 1. Add the following filter: |
90 * Include only | 137 * Include only |
91 * Files, all children (recursive) | 138 * Files, all children (recursive) |
92 * Name matches `.*\.(c|cc|cpp|h|mm|inl|idl|js|json|css|html|gyp|gypi|grd|grd
p|gn)` regular expression | 139 * Name matches |
93 1. Add another filter: | 140 `.*\.(c|cc|cpp|h|mm|inl|idl|js|json|css|html|gyp|gypi|grd|grdp|gn)` |
94 * Exclude all | 141 regular expression |
95 * Folders | 142 1. Add another filter: |
96 * Name matches `out_.*|\.git|\.svn|LayoutTests` regular expression | 143 * Exclude all |
97 * If you aren't working on WebKit, adding `|WebKit` will remove more files | 144 * Folders |
98 1. Click "OK" | 145 * Name matches `out_.*|\.git|\.svn|LayoutTests` regular expression |
99 | 146 * If you aren't working on WebKit, adding `|WebKit` will remove more |
100 Don't exclude the primary "out" directory, as it contains generated header files
for things like string resources and Eclipse will miss a lot of symbols if you
do. | 147 files |
101 | 148 1. Click "OK" |
102 Eclipse will refresh the workspace and start indexing your code. It won't find
most header files, however. Give it more help finding them: | 149 |
103 | 150 Don't exclude the primary "out" directory, as it contains generated header files |
104 1. Open Window > Preferences | 151 for things like string resources and Eclipse will miss a lot of symbols if you |
105 1. Search for "Indexer" | 152 do. |
106 1. Turn on "Allow heuristic resolution of includes" | 153 |
107 1. Select "Use active build configuration" | 154 Eclipse will refresh the workspace and start indexing your code. It won't find |
108 1. Set Cache limits > Index database > Limit relative... to 20% | 155 most header files, however. Give it more help finding them: |
109 1. Set Cache limits > Index database > Absolute limit to 256 MB | 156 |
110 1. Click "OK" | 157 1. Open Window > Preferences |
111 | 158 1. Search for "Indexer" |
112 Now the indexer will find many more include files, regardless of which approach
you take below. | 159 1. Turn on "Allow heuristic resolution of includes" |
113 | 160 1. Select "Use active build configuration" |
114 ### Optional: Manual header paths and symbols | 161 1. Set Cache limits > Index database > Limit relative... to 20% |
115 You can manually tell Eclipse where to find header files, which will allow it to
create the source code index before you do a real build. | 162 1. Set Cache limits > Index database > Absolute limit to 256 MB |
116 | 163 1. Click "OK" |
117 1. Right-click on "src" and select "Properties..." | 164 |
| 165 Now the indexer will find many more include files, regardless of which approach |
| 166 you take below. |
| 167 |
| 168 #### Optional: Manual header paths and symbols |
| 169 |
| 170 You can manually tell Eclipse where to find header files, which will allow it to |
| 171 create the source code index before you do a real build. |
| 172 |
| 173 1. Right-click on "src" and select "Properties..." |
118 * Open C++ General > Paths and Symbols > Includes | 174 * Open C++ General > Paths and Symbols > Includes |
119 * Click "GNU C++" | 175 * Click "GNU C++" |
120 * Click "Add..." | 176 * Click "Add..." |
121 * Add /path/to/chromium/src | 177 * Add `/path/to/chromium/src` |
122 * Check "Add to all configurations" and "Add to all languages" | 178 * Check "Add to all configurations" and "Add to all languages" |
123 1. Repeat the above for: | 179 1. Repeat the above for: |
124 * /path/to/chromium/src/testing/gtest/include | 180 * `/path/to/chromium/src/testing/gtest/include` |
125 | 181 |
126 You may also find it helpful to define some symbols. | 182 You may also find it helpful to define some symbols. |
127 | 183 |
128 1. Add OS\_LINUX: | 184 1. Add `OS_LINUX`: |
129 * Select the "Symbols" tab | 185 * Select the "Symbols" tab |
130 * Click "GNU C++" | 186 * Click "GNU C++" |
131 * Click "Add..." | 187 * Click "Add..." |
132 * Add name OS\_LINUX with value 1 | 188 * Add name `OS_LINUX` with value 1 |
133 * Click "Add to all configurations" and "Add to all languages" | 189 * Click "Add to all configurations" and "Add to all languages" |
134 1. Repeat for ENABLE\_EXTENSIONS 1 | 190 1. Repeat for `ENABLE_EXTENSIONS 1` |
135 1. Repeat for HAS\_OUT\_OF\_PROC\_TEST\_RUNNER 1 | 191 1. Repeat for `HAS_OUT_OF_PROC_TEST_RUNNER 1` |
136 1. Click "OK". | 192 1. Click "OK". |
137 1. Eclipse will ask if you want to rebuild the index. Click "Yes". | 193 1. Eclipse will ask if you want to rebuild the index. Click "Yes". |
138 | 194 |
139 Let the C++ indexer run. It will take a while (10s of minutes). | 195 Let the C++ indexer run. It will take a while (10s of minutes). |
140 | 196 |
141 ## Optional: Building inside Eclipse | 197 ### Optional: Building inside Eclipse |
142 This allows Eclipse to automatically discover include directories and symbols.
If you use gold or ninja (both recommended) you'll need to tell Eclipse about yo
ur path. | 198 |
143 | 199 This allows Eclipse to automatically discover include directories and symbols. |
144 1. echo $PATH from a shell and copy it to the clipboard | 200 If you use gold or ninja (both recommended) you'll need to tell Eclipse about |
145 1. Open Window > Preferences > C/C++ > Build > Environment | 201 your path. |
146 1. Select "Replace native environment with specified one" (since gold and ninj
a must be at the start of your path) | 202 |
147 1. Click "Add..." | 203 1. echo $PATH from a shell and copy it to the clipboard |
148 1. For name, enter `PATH` | 204 1. Open Window > Preferences > C/C++ > Build > Environment |
149 1. For value, paste in your path with the ninja and gold directories. | 205 1. Select "Replace native environment with specified one" (since gold and ninja |
150 1. Click "OK" | 206 must be at the start of your path) |
| 207 1. Click "Add..." |
| 208 1. For name, enter `PATH` |
| 209 1. For value, paste in your path with the ninja and gold directories. |
| 210 1. Click "OK" |
151 | 211 |
152 To create a Make target: | 212 To create a Make target: |
153 | 213 |
154 1. From the Window menu, select Show View > Make Target | 214 1. From the Window menu, select Show View > Make Target |
155 1. In the Make Target view, right-click on the project and select New... | 215 1. In the Make Target view, right-click on the project and select New... |
156 1. name the target (e.g. base\_unittests) | 216 1. name the target (e.g. base\_unittests) |
157 1. Unclick the Build Command: Use builder Settings and type whatever build com
mand you would use to build this target (e.g. "ninja -C out/Debug base\_unittest
s"). | 217 1. Unclick the Build Command: Use builder Settings and type whatever build |
158 1. Return to the project properties page a under the C/C++ Build, change the B
uild Location/Build Directory to be /path/to/chromium/src | 218 command you would use to build this target (e.g. |
159 1. In theory ${workspace\_loc} should work, but it doesn't for me. | 219 `ninja -C out/Debug base_unittests`). |
160 1. If you put your workspace in /path/to/chromium, then ${workspace\_loc:/sr
c} will work too. | 220 1. Return to the project properties page a under the C/C++ Build, change the |
161 1. Now in the Make Targets view, select the target and click the hammer icon (
Build Make Target). | 221 Build Location/Build Directory to be /path/to/chromium/src |
162 | 222 1. In theory `${workspace_loc}` should work, but it doesn't for me. |
163 You should see the build proceeding in the Console View and errors will be parse
d and appear in the Problems View. (Note that sometimes multi-line compiler erro
rs only show up partially in the Problems view and you'll want to look at the fu
ll error in the Console). | 223 1. If you put your workspace in `/path/to/chromium`, then |
164 | 224 `${workspace_loc:/src}` will work too. |
165 (Eclipse 3.8 has a bug where the console scrolls too slowly if you're doing a fa
st build, e.g. with goma. To work around, go to Window > Preferences and search
for "console". Under C/C++ console, set "Limit console output" to 2147483647,
the maximum value.) | 225 1. Now in the Make Targets view, select the target and click the hammer icon |
166 | 226 (Build Make Target). |
167 ## Optional: Multiple build targets | 227 |
168 If you want to build multiple different targets in Eclipse (chrome, unit\_tests,
etc.): | 228 You should see the build proceeding in the Console View and errors will be |
169 | 229 parsed and appear in the Problems View. (Note that sometimes multi-line compiler |
170 1. Window > Show Toolbar (if you had it off) | 230 errors only show up partially in the Problems view and you'll want to look at |
171 1. Turn on special toolbar menu item (hammer) or menu bar item (Project > Buil
d configurations > Set Active > ...) | 231 the full error in the Console). |
172 1. Window > Customize Perspective... > "Command Groups Availability" | 232 |
173 1. Check "Build configuration" | 233 (Eclipse 3.8 has a bug where the console scrolls too slowly if you're doing a |
174 1. Add more Build targets | 234 fast build, e.g. with goma. To work around, go to Window > Preferences and |
175 1. Project > Properties > C/C++ Build > Manage Configurations | 235 search for "console". Under C/C++ console, set "Limit console output" to |
176 1. Select "New..." | 236 2147483647, the maximum value.) |
177 1. Duplicate from current and give it a name like "Unit tests". | 237 |
178 1. Change under “Behavior” > Build > the target to e.g. “unit\_tests”. | 238 ### Optional: Multiple build targets |
179 | 239 |
180 You can also drag the toolbar to the bottom of your window to save vertical spac
e. | 240 If you want to build multiple different targets in Eclipse (`chrome`, |
181 | 241 `unit_tests`, etc.): |
182 ## Optional: Debugging | 242 |
183 | 243 1. Window > Show Toolbar (if you had it off) |
184 1. From the toolbar at the top, click the arrow next to the debug icon and sel
ect Debug Configurations... | 244 1. Turn on special toolbar menu item (hammer) or menu bar item (Project > Build |
185 1. Select C/C++ Application and click the New Launch Configuration icon. This
will create a new run/debug configuration under the C/C++ Application header. | 245 configurations > Set Active > ...) |
186 1. Name it something useful (e.g. base\_unittests). | 246 1. Window > Customize Perspective... > "Command Groups Availability" |
187 1. Under the Main Tab, enter the path to the executable (e.g. .../out/Debug/ba
se\_unittests) | 247 1. Check "Build configuration" |
188 1. Select the Debugger Tab, select Debugger: gdb and unclick "Stop on startup
in (main)" unless you want this. | 248 1. Add more Build targets |
189 1. Set a breakpoint somewhere in your code and click the debug icon to start d
ebugging. | 249 1. Project > Properties > C/C++ Build > Manage Configurations |
190 | 250 1. Select "New..." |
191 ## Optional: Accurate symbol information | 251 1. Duplicate from current and give it a name like "Unit tests". |
192 | 252 1. Change under “Behavior” > Build > the target to e.g. `unit_tests`. |
193 If setup properly, Eclipse can do a great job of semantic navigation of C++ code
(showing type hierarchies, finding all references to a particular method even w
hen other classes have methods of the same name, etc.). But doing this well req
uires the Eclipse knows correct include paths and pre-processor definitions. Af
ter fighting with with a number of approaches, I've found the below to work best
for me. | 253 |
194 | 254 You can also drag the toolbar to the bottom of your window to save vertical |
195 1. From a shell in your src directory, run GYP\_GENERATORS=ninja,eclipse build
/gyp\_chromium | 255 space. |
196 1. This generates <project root>/out/Debug/eclipse-cdt-settings.xml which is
used below. | 256 |
197 1. This creates a single list of include directories and preprocessor defini
tions to be used for all source files, and so is a little inaccurate. Here are
some tips for compensating for the limitations: | 257 ### Optional: Debugging |
198 1. Use `-R <target>` to restrict the output to considering only certain ta
rgets (avoiding unnecessary includes that are likely to cause trouble). Eg. for
a blink project, use `-R blink`. | 258 |
199 1. If you care about blink, move 'third\_party/Webkit/Source' to the top o
f the list to better resolve ambiguous include paths (eg. 'config.h'). | 259 1. From the toolbar at the top, click the arrow next to the debug icon and |
200 1. Import paths and symbols | 260 select Debug Configurations... |
201 1. Right click on the project and select Properties > C/C++ General > Paths
and Symbols | 261 1. Select C/C++ Application and click the New Launch Configuration icon. This |
202 1. Click Restore Defaults to clear any old settings | 262 will create a new run/debug con figuration under the C/C++ Application heade
r. |
203 1. Click Import Settings... > Browse... and select <project root>/out/Debug/
eclipse-cdt-settings.xml | 263 1. Name it something useful (e.g. `base_unittests`). |
204 1. Click the Finish button. The entire preferences dialog should go away. | 264 1. Under the Main Tab, enter the path to the executable (e.g. |
205 1. Right click on the project and select Index > Rebuild | 265 `.../out/Debug/base_unittests`) |
206 | 266 1. Select the Debugger Tab, select Debugger: gdb and unclick "Stop on startup |
207 ## Alternative: Per-file accurate include/pre-processor information | 267 in (main)" unless you want this. |
208 | 268 1. Set a breakpoint somewhere in your code and click the debug icon to start |
209 Instead of generating a fixed list of include paths and pre-processor definition
s for a project (above), it is also possible to have Eclipse determine the corre
ct setting on a file-by-file basis using a built output parser. I (rbyers) used
this successfully for a long time, but it doesn't seem much better in practice
than the simpler (and less bug-prone) approach above. | 269 debugging. |
210 | 270 |
211 1. Install the latest version of Eclipse IDE for C/C++ developers ([Juno SR1](
http://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/junosr1) at
the time of this writing) | 271 ### Optional: Accurate symbol information |
212 1. Setup build to generate a build log that includes the g++ command lines for
the files you want to index: | 272 |
213 1. Project Properties -> C/C++ Build | 273 If setup properly, Eclipse can do a great job of semantic navigation of C++ code |
214 1. Uncheck "Use default build command" | 274 (showing type hierarchies, finding all references to a particular method even |
215 1. Enter your build command, eg: ninja -v | 275 when other classes have methods of the same name, etc.). But doing this well |
216 1. Note that for better performance, you can use a command that doesn't
actually builds, just prints the commands that would be run. For ninja/make thi
s means adding -n. This only prints the compile commands for changed files (so b
e sure to move your existing out directory out of the way temporarily to force a
full "build"). ninja also supports "-t commands" which will print all build com
mands for the specified target and runs even faster as it doesn't have to check
file timestamps. | 276 requires the Eclipse knows correct include paths and pre-processor definitions. |
217 1. Build directory: your build path including out/Debug | 277 After fighting with with a number of approaches, I've found the below to work |
218 1. Note that for the relative paths to be parsed correctly you can't use
ninja's ` '-C <dir>' ` to change directories as you might from the command line
. | 278 best for me. |
219 1. Build: potentially change "all" to the target you want to analyze, eg.
"chrome" | 279 |
220 1. Deselect 'clean' | 280 1. From a shell in your src directory, run |
221 1. If you're using Ninja, you need to teach eclipse to ignore the prefix it
adds (eg. [10/1234] to each line in build output): | 281 `GYP_GENERATORS=ninja,eclipse build/gyp_chromium` |
222 1. Project properties -> C/C++ General -> Preprocessor includes | 282 1. This generates <project root>/out/Debug/eclipse-cdt-settings.xml which |
223 1. Providers -> CDT GCC Build Output Parser -> Compiler command pattern | 283 is used below. |
224 1. ` (\[.*\] )?((gcc)|([gc]\+\+)|(clang(\+\+)?)) ` | 284 1. This creates a single list of include directories and preprocessor |
225 1. Note that there appears to be a bug with "Share setting entries between
projects" - it will keep resetting to off. I suggest using per-project setting
s and using the "folder" as the container to keep discovered entries ("file" may
work as well). | 285 definitions to be used for all source files, and so is a little |
226 1. Eclipse / GTK has bugs where lots of output to the build console can slow
down the UI dramatically and cause it to hang (basically spends all it's time t
rying to position the cursor correctly in the build console window). To avoid t
his, close the console window and disable automatically opening it on build: | 286 inaccurate. Here are some tips for compensating for the limitations: |
227 1. Preferences->C/C++->Build->Console -> Uncheck "Open console when buildi
ng" | 287 1. Use `-R <target>` to restrict the output to considering only certain |
228 1. note you can still see the build log in ` <workspace>/.metadata/.plugin
s/org.eclipse.cdt.ui ` | 288 targets (avoiding unnecessary includes that are likely to cause |
229 1. Now build the project (select project, click on hammer). If all went well: | 289 trouble). Eg. for a blink project, use `-R blink`. |
230 1. Right click on a cpp file -> properties -> C/C++ general -> Preprocessor
includes -> GNU C++ -> CDT GCC Build output Parser | 290 1. If you care about blink, move 'third\_party/Webkit/Source' to the |
231 1. You will be able to expand and see all the include paths and pre-processo
r definitions used for this file | 291 top of the list to better resolve ambiguous include paths (eg. |
232 1. Rebuild index (right-click on project, index, rebuild). If all went well: | 292 `config.h`). |
233 1. Open a CPP file and look at problems windows | 293 1. Import paths and symbols |
234 1. Should be no (or very few) errors | 294 1. Right click on the project and select Properties > C/C++ General > Paths |
235 1. Should be able to hit F3 on most symbols and jump to their definitioin | 295 and Symbols |
236 1. CDT has some issues with complex C++ syntax like templates (eg. PassOwnPt
r functions) | 296 1. Click Restore Defaults to clear any old settings |
237 1. See [this page](http://wiki.eclipse.org/CDT/User/FAQ#Why_does_Open_Declar
ation_.28F3.29_not_work.3F_.28also_applies_to_other_functions_using_the_indexer.
29) for more information. | 297 1. Click Import Settings... > Browse... and select |
238 | 298 `<project root>/out/Debug/eclipse-cdt-settings.xml` |
239 ## Optional: static code and style guide analysis using cpplint.py | 299 1. Click the Finish button. The entire preferences dialog should go away. |
240 | 300 1. Right click on the project and select Index > Rebuild |
241 1. From the toolbar at the top, click the Project -> Properties and go to C/C+
+Build. | 301 |
242 1. Click on the right side of the pop up windows, "Manage Configurations..."
, then on New, and give it a name, f.i. "Lint current file", and close the small
window, then select it in the Configuration drop down list. | 302 ### Alternative: Per-file accurate include/pre-processor information |
243 1. Under Builder settings tab, unclick "Use default build command" and type
as build command the full path to your depot\_tools/cpplint.py | 303 |
244 1. Under behaviour tab, unselect Clean, select Build(incremental build) and
in Make build target, add `--verbose=0 ${selected_resource_loc} ` | 304 Instead of generating a fixed list of include paths and pre-processor |
245 1. Go back to the left side of the current window, and to C/C++Build -> Sett
ings, and click on error parsers tab, make sure CDT GNU C/C++ Error Parser, CDT
pushd/popd CWD Locator are set, then click Apply and OK. | 305 definitions for a project (above), it is also possible to have Eclipse determine |
246 1. Select a file and click on the hammer icon drop down triangle next to it, a
nd make sure the build configuration is selected "Lint current file", then click
on the hammer. | 306 the correct setting on a file-by-file basis using a built output parser. I |
247 1. Note: If you get the cpplint.py help output, make sure you have selected a
file, by clicking inside the editor window or on its tab header, and make sure t
he editor is not maximized inside Eclipse, i.e. you should see more subwindows a
round. | 307 (rbyers) used this successfully for a long time, but it doesn't seem much better |
248 | 308 in practice than the simpler (and less bug-prone) approach above. |
249 ## Additional tips | 309 |
250 1. Mozilla's [Eclipse CDT guide](https://developer.mozilla.org/en-US/docs/Ecli
pse_CDT) is helpful: | 310 1. Install the latest version of Eclipse IDE for C/C++ developers |
251 1. For improved performance, I use medium-granularity projects (eg. one for We
bKit/Source) instead of putting all of 'src/' in one project. | 311 ([Juno SR1](http://www.eclipse.org/downloads/packages/eclipse-ide-cc-develop
ers/junosr1) |
252 1. For working in Blink (which uses WebKit code style), feel free to use [this
](https://drive.google.com/file/d/0B2LVVIKSxUVYM3R6U0tUa1dmY0U/view?usp=sharing)
code-style formatter XML profile | 312 at the time of this writing) |
| 313 1. Setup build to generate a build log that includes the g++ command lines for |
| 314 the files you want to index: |
| 315 1. Project Properties -> C/C++ Build |
| 316 1. Uncheck "Use default build command" |
| 317 1. Enter your build command, eg: `ninja -v` |
| 318 1. Note that for better performance, you can use a command that |
| 319 doesn't actually builds, just prints the commands that would be |
| 320 run. For ninja/make this means adding -n. This only prints the |
| 321 compile commands for changed files (so be sure to move your |
| 322 existing out directory out of the way temporarily to force a |
| 323 full "build"). ninja also supports "-t commands" which will |
| 324 print all build commands for the specified target and runs even |
| 325 faster as it doesn't have to check file timestamps. |
| 326 1. Build directory: your build path including out/Debug |
| 327 1. Note that for the relative paths to be parsed correctly you |
| 328 can't use ninja's `-C <dir>` to change directories as you might |
| 329 from the command line. |
| 330 1. Build: potentially change `all` to the target you want to analyze, |
| 331 eg. `chrome` |
| 332 1. Deselect 'clean' |
| 333 1. If you're using Ninja, you need to teach eclipse to ignore the prefix it |
| 334 adds (eg. `[10/1234]` to each line in build output): |
| 335 1. Project properties -> C/C++ General -> Preprocessor includes |
| 336 1. Providers -> CDT GCC Build Output Parser -> Compiler command pattern |
| 337 1. `(\[.*\] )?((gcc)|([gc]\+\+)|(clang(\+\+)?))` |
| 338 1. Note that there appears to be a bug with "Share setting entries |
| 339 between projects" - it will keep resetting to off. I suggest using |
| 340 per-project settings and using the "folder" as the container to keep |
| 341 discovered entries ("file" may work as well). |
| 342 1. Eclipse / GTK has bugs where lots of output to the build console can |
| 343 slow down the UI dramatically and cause it to hang (basically spends all |
| 344 it's time trying to position the cursor correctly in the build console |
| 345 window). To avoid this, close the console window and disable |
| 346 automatically opening it on build: |
| 347 1. Preferences->C/C++->Build->Console -> Uncheck "Open console when |
| 348 building" |
| 349 1. note you can still see the build log in |
| 350 `<workspace>/.metadata/.plugins/org.eclipse.cdt.ui` |
| 351 1. Now build the project (select project, click on hammer). If all went well: |
| 352 1. Right click on a cpp file -> properties -> C/C++ general -> Preprocessor |
| 353 includes -> GNU C++ -> CDT GCC Build output Parser |
| 354 1. You will be able to expand and see all the include paths and |
| 355 pre-processor definitions used for this file |
| 356 1. Rebuild index (right-click on project, index, rebuild). If all went well: |
| 357 1. Open a CPP file and look at problems windows |
| 358 1. Should be no (or very few) errors |
| 359 1. Should be able to hit F3 on most symbols and jump to their definitioin |
| 360 1. CDT has some issues with complex C++ syntax like templates (eg. |
| 361 `PassOwnPtr` functions) |
| 362 1. See |
| 363 [this page](http://wiki.eclipse.org/CDT/User/FAQ#Why_does_Open_Declarati
on_.28F3.29_not_work.3F_.28also_applies_to_other_functions_using_the_indexer.29) |
| 364 for more information. |
| 365 |
| 366 ### Optional: static code and style guide analysis using cpplint.py |
| 367 |
| 368 1. From the toolbar at the top, click the Project -> Properties and go to |
| 369 C/C++Build. |
| 370 1. Click on the right side of the pop up windows, "Manage |
| 371 Configurations...", then on New, and give it a name, f.i. "Lint current |
| 372 file", and close the small window, then select it in the Configuration |
| 373 drop down list. |
| 374 1. Under Builder settings tab, unclick "Use default build command" and type |
| 375 as build command the full path to your `depot_tools/cpplint.py` |
| 376 1. Under behaviour tab, unselect Clean, select Build(incremental build) and |
| 377 in Make build target, add `--verbose=0 ${selected_resource_loc}` |
| 378 1. Go back to the left side of the current window, and to C/C++Build -> |
| 379 Settings, and click on error parsers tab, make sure CDT GNU C/C++ Error |
| 380 Parser, CDT pushd/popd CWD Locator are set, then click Apply and OK. |
| 381 1. Select a file and click on the hammer icon drop down triangle next to it, |
| 382 and make sure the build configuration is selected "Lint current file", then |
| 383 click on the hammer. |
| 384 1. Note: If you get the `cpplint.py help` output, make sure you have selected a |
| 385 file, by clicking inside the editor window or on its tab header, and make |
| 386 sure the editor is not maximized inside Eclipse, i.e. you should see more |
| 387 subwindows around. |
| 388 |
| 389 ### Additional tips |
| 390 |
| 391 1. Mozilla's |
| 392 [Eclipse CDT guide](https://developer.mozilla.org/en-US/docs/Eclipse_CDT) |
| 393 is helpful: |
| 394 1. For improved performance, I use medium-granularity projects (eg. one for |
| 395 WebKit/Source) instead of putting all of 'src/' in one project. |
| 396 1. For working in Blink (which uses WebKit code style), feel free to use |
| 397 [this](https://drive.google.com/file/d/0B2LVVIKSxUVYM3R6U0tUa1dmY0U/view?usp
=sharing) |
| 398 code-style formatter XML profile |
OLD | NEW |