|
1
|
Using IDE for Fossil Development |
|
2
|
================================ |
|
3
|
|
|
4
|
Overview |
|
5
|
-------- |
|
6
|
|
|
7
|
IDE is not required to build Fossil. However, IDE may be useful in development |
|
8
|
of the Fossil code. Staple IDE features that come to mind are ease of editing, |
|
9
|
static code analysis, source indexing, autocomplete, and integrated |
|
10
|
debugging. |
|
11
|
|
|
12
|
Who may benefit from using an IDE? In general sense, of course, anyone who is |
|
13
|
used to a particular IDE. Specifically to Fossil development this could be: |
|
14
|
|
|
15
|
* Developers who are __new to Fossil code__; IDE helps navigate definitions |
|
16
|
and implementations across the source files |
|
17
|
|
|
18
|
* Developers who may be familiar with the code, yet would want to diagnose |
|
19
|
an issue that calls for __in-depth debugging__; IDE makes debugging |
|
20
|
somewhat more accessible |
|
21
|
|
|
22
|
[Current Fossil build process](./makefile.wiki) is Makefile-based, which |
|
23
|
extensively uses code-generation. It's flexible, yet as such it's not natively |
|
24
|
fitting any specific IDE. This often represents a challenge for an IDE workflow |
|
25
|
as it's trying to figure out the correct dependencies. |
|
26
|
|
|
27
|
To assist with Fossil IDE workflow, there're currently two alternatives to |
|
28
|
consider depending on IDE capabilities to support it: |
|
29
|
|
|
30
|
* [Use CMake-based workflow](#cmake-workflow); in this case the Fossil's |
|
31
|
[CMakeLists.txt](/file/CMakeLists.txt) file is directly used as the IDE |
|
32
|
project file |
|
33
|
|
|
34
|
* [Import the existing Makefile](#import-makefile) and then tweak the |
|
35
|
resulting project settings to properly reference the dependencies |
|
36
|
|
|
37
|
The following sections describe both approaches as tested with a selection of |
|
38
|
IDEs (not exhaustive). |
|
39
|
|
|
40
|
|
|
41
|
> __USAGE NOTES__: To get most utility out of IDE in Fossil development, it's |
|
42
|
> recommended to do a general development in _Release_ build configuration. |
|
43
|
> In this case, compile errors would refer to original source files instead |
|
44
|
> of the generated ones which actually get compiled. Clicking on such error |
|
45
|
> message in the IDE output pane will bring up the source file and the |
|
46
|
> offending line. |
|
47
|
> |
|
48
|
> This somewhat reduces chances of making edits in the generated files just |
|
49
|
> to see the precious code lost as the files get re-generated during build. |
|
50
|
> |
|
51
|
> Switch to _Debug_ build configuration once in a need to chase that bug |
|
52
|
> that is playing hard to get. The debugger is stepping through the actually |
|
53
|
> compiled code, that is the editor will load the generated files from the |
|
54
|
> build directory. While fixing the bugs, just be aware of where to make the |
|
55
|
> edits. |
|
56
|
> |
|
57
|
> A simple rule of thumb is to keep only `<module>.c` source files open, |
|
58
|
> closing the files `<module>_.c` (underscored) and `<module>.h` (header) |
|
59
|
> which get generated in the build directory. |
|
60
|
|
|
61
|
|
|
62
|
> __WARNING__: Edits to _generated_ files in the build directory will __NOT__ |
|
63
|
> survive a _Rebuild_, and the changes cannot be committed directly to the |
|
64
|
> project repository. |
|
65
|
> |
|
66
|
> Make sure you edit files in the Fossil __source__ directories. |
|
67
|
|
|
68
|
|
|
69
|
<a name="cmake-workflow"></a> |
|
70
|
CMake-based Fossil Workflow |
|
71
|
--------------------------- |
|
72
|
|
|
73
|
Most major C/C++ IDEs handle CMake projects either natively or via native |
|
74
|
project files generated from the given [CMakeLists.txt](/file/CMakeLists.txt). |
|
75
|
|
|
76
|
So far the Fossil CMake-based workflow has been tried with the following IDEs: |
|
77
|
|
|
78
|
* [Qt Creator](#cmake-qtc) (Linux, Windows) |
|
79
|
* [VisualStudio 2017](#cmake-vs) (Windows) |
|
80
|
* [Eclipse CDT](#cmake-eclipse) (Linux) |
|
81
|
* [VSCode](#cmake-vscode) (Linux, Windows) |
|
82
|
* [Code::Blocks](#cmake-cb) (Linux) |
|
83
|
|
|
84
|
|
|
85
|
<a name="cmake-cmd"></a> |
|
86
|
__Using CMake on the Command-line__ |
|
87
|
|
|
88
|
In general, the CMake workflow is very much the same on all of the supported |
|
89
|
platforms. CMake generator takes care of the platform/compiler specifics. |
|
90
|
|
|
91
|
CMake can be used directly on the command-line to build the Fossil project in |
|
92
|
either Release or Debug configuration: |
|
93
|
|
|
94
|
cd fossil |
|
95
|
mkdir build-debug |
|
96
|
cd build-debug |
|
97
|
cmake .. -G"Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug |
|
98
|
make |
|
99
|
|
|
100
|
OR on Windows with MSVC: |
|
101
|
|
|
102
|
cmake .. -G"NMake Makefiles" -DCMAKE_BUILD_TYPE=Debug |
|
103
|
nmake |
|
104
|
|
|
105
|
An IDE executes similar commands behind the scenes to generate and build a |
|
106
|
CMake-based project. In general, CMake is capable of generating native project |
|
107
|
files for a wide selection of IDEs. However for the Fossil CMake project, it's |
|
108
|
preferable to generate a __Makefiles__ build system, because that's what the |
|
109
|
underlying Fossil build process is. |
|
110
|
|
|
111
|
Below are the steps used to setup Fossil CMake project in the IDEs tested. |
|
112
|
|
|
113
|
|
|
114
|
> __NOTE__: To refresh a _Project Tree View_ so that it shows the generated |
|
115
|
> files, the easiest way is to re-save the `CMakeLists.txt` file. This |
|
116
|
> triggers the IDE tools to regenerate the build system and rescan the project |
|
117
|
> source files. |
|
118
|
|
|
119
|
|
|
120
|
<a name="cmake-qtc"></a> |
|
121
|
__Qt Creator__ |
|
122
|
|
|
123
|
CMake workflow in Qt Creator has been supported for quite some time, so it |
|
124
|
evolved to become more streamlined. Below are the steps to set up CMake |
|
125
|
project in Qt Creator version 4.5 and above. |
|
126
|
|
|
127
|
1. From Weclome panel _Open Project_, browse to the Fossil project directory |
|
128
|
and open the `CMakeLists.txt` file. |
|
129
|
1. Qt Creator will prompt to select a _Kit_ to configure the project. |
|
130
|
For example, `Desktop Qt 5.9.4 GCC 64bit` |
|
131
|
|
|
132
|
At this point the project is already usable. Optionally, for convenience it |
|
133
|
makes sense to adjust some of the default settings. |
|
134
|
|
|
135
|
1. Open the _Projects_ panel |
|
136
|
1. Remove the extra build configurations, keep Debug and Release |
|
137
|
1. For each of the build configurations |
|
138
|
|
|
139
|
* Select a _Build directory_. For example: `build-fossil-debug/` |
|
140
|
directory or `build-debug/` subdirectory. |
|
141
|
* Set any additional CMake variables |
|
142
|
|
|
143
|
Now it's ready for build and use. |
|
144
|
|
|
145
|
1. Select the build configuration; for example `Debug` |
|
146
|
1. Do _Build Project "fossil"_; it runs the CMake and then starts the build |
|
147
|
showing the progress in the _Compile Output_ pane |
|
148
|
1. Refresh the _Projects Explorer View_ so that it shows the generated files: |
|
149
|
|
|
150
|
* Open the `CMakeLists.txt` file and trivially "touch" it then re-save |
|
151
|
it. |
|
152
|
* This triggers CMake which then re-populates the _Project Explorer View_ |
|
153
|
adding the generated header files from the build directory. |
|
154
|
1. Navigate definitions/implementations. For example, in `src/main.c` |
|
155
|
function `version_cmd()` for the function `fossil_print()` select context |
|
156
|
menu _Follow Symbol Under Cursor_ -- the Fossil source file `src/printf.c` |
|
157
|
automatically opens in editor. |
|
158
|
1. Set the run arguments -- panel _Projects: Run_; by default the `app` |
|
159
|
target is already selected (`bin/fossil` executable): |
|
160
|
|
|
161
|
* Set the _Command line arguments:_ for example, `version` |
|
162
|
* Optionally, check _Run in terminal_ |
|
163
|
1. Do _Run_ OR |
|
164
|
1. To start debugging -- do menu _Debug> Step Into_; the editor opens file |
|
165
|
`main_.c` (generated!!), execution stops in `main()`. Fossil executable |
|
166
|
output is shown in a separate terminal window. |
|
167
|
|
|
168
|
> __WARNING__: Edits to _generated_ files in the build directory will __NOT__ |
|
169
|
> survive a _Rebuild_, and the changes cannot be committed directly to the |
|
170
|
> project repository. |
|
171
|
> |
|
172
|
> Make sure you edit files in the Fossil __source__ directories. |
|
173
|
|
|
174
|
|
|
175
|
<a name="cmake-vs"></a> |
|
176
|
__Visual Studio 2017__ |
|
177
|
|
|
178
|
Starting with Visual Studio 2017 CMake-based projects (`CMakeLists.txt` files) |
|
179
|
are directly supported without the need to generate an intermediate MSBuild |
|
180
|
project files. This feature is supported via _Visual C++ Tools for CMake_ |
|
181
|
component which is installed by default as part of the |
|
182
|
__Desktop development with C++__ workload. |
|
183
|
|
|
184
|
|
|
185
|
> __NOTE__: By default, Visual Studio 2017 CMake Tools uses Ninja build tool. |
|
186
|
> In general it has a better performance over the usual NMake, as it allows |
|
187
|
> parallel build tasks. However in the scope of Fossil CMake project there's |
|
188
|
> no real speedup, since the underlying Fossil Makefile is still built with |
|
189
|
> NMake. |
|
190
|
> |
|
191
|
> As Ninja tool has some subtle differences in handling of the `clean` target, |
|
192
|
> it's recommended to select the `"NMake Makefiles"` generator for the Fossil |
|
193
|
> CMake project (which is a valid choice despite a possible warning.) |
|
194
|
|
|
195
|
|
|
196
|
1. Menu _File> Open:Folder_ to open Fossil source project directory that |
|
197
|
contains the `CMakeLists.txt` file |
|
198
|
1. Change the generator -- menu _CMake> Change CMake Settings> fossil_ will |
|
199
|
open `CMakeSettings.json` file; in all of the defined configurations set: |
|
200
|
|
|
201
|
"generator": "NMake Makefiles", |
|
202
|
"buildCommandArgs": "", |
|
203
|
Save the settings file and the project is reconfigured automatically. |
|
204
|
1. Select configuration -- toolbar _Select Project Settings_, for example: |
|
205
|
`x64-Debug` |
|
206
|
1. Do menu _CMake> Build All_; build progress is shown in _Output:Build_ pane |
|
207
|
1. Navigate definitions/implementations. For example, in `src/main.c` |
|
208
|
function `version_cmd()` for the function `fossil_print()` select context |
|
209
|
menu _Peek Definition_ -- the Fossil source file `src/printf.c` |
|
210
|
automatically opens the peek preview pane. |
|
211
|
1. Select a start target `bin/fossil.exe` -- toolbar _Select Startup Item_ |
|
212
|
1. Set the run arguments -- menu _CMake> Debug and Launch Settings_ in the |
|
213
|
file `.vs/launch.vs.json`. For example, for _"default"_ configuration |
|
214
|
append: |
|
215
|
|
|
216
|
"args": ["version"] |
|
217
|
Save the settings file. |
|
218
|
1. To start debugging -- do menu _Debug> Step Into_; the editor opens file |
|
219
|
`main_.c` (generated!!), execution stops in `main()`. Fossil executable |
|
220
|
output is shown in a separate terminal window. |
|
221
|
|
|
222
|
|
|
223
|
> __WARNING__: Edits to _generated_ files in the build directory will __NOT__ |
|
224
|
> survive a _Rebuild_, and the changes cannot be committed directly to the |
|
225
|
> project repository. |
|
226
|
> |
|
227
|
> Make sure you edit files in the Fossil __source__ directories. |
|
228
|
|
|
229
|
|
|
230
|
> __NOTE__: If doing a cross-platform build, it's necessary to clean the |
|
231
|
> builds of the external components that are used with Fossil (in `compat/` |
|
232
|
> subdirectory). For example, `zlib`, `openssl`. Failure to do that may |
|
233
|
> manifest with the fireworks of compile and link errors. |
|
234
|
|
|
235
|
|
|
236
|
<a name="cmake-eclipse"></a> |
|
237
|
__Eclipse CDT__ |
|
238
|
|
|
239
|
To configure CMake-based project with Eclipse it first has to be generated as |
|
240
|
a native project, then imported into Eclipse as an existing project. |
|
241
|
|
|
242
|
The CMake build directory should __not__ be a subdirectory of the Fossil |
|
243
|
project source directory, but rather a sibling or other directory. For example: |
|
244
|
|
|
245
|
workspace/ |
|
246
|
|-- fossil-debug/ <== CMake build directory |
|
247
|
|-- fossil/ <== Fossil project directory |
|
248
|
| `-- CMakeLists.txt |
|
249
|
`-- fossil-release/ |
|
250
|
|
|
251
|
1. Generate Eclipse CDT4 makefiles, optionally specify the Eclipse's version: |
|
252
|
|
|
253
|
cd workspace |
|
254
|
cd debug |
|
255
|
cmake ../fossil -G"Eclipse CDT4 - Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug |
|
256
|
-DCMAKE_ECLIPSE_VERSION=3.8 |
|
257
|
ls .cproject |
|
258
|
|
|
259
|
1. From Eclipse do _Import_ as a _General>Existing Projects into Workspace_ |
|
260
|
from within the CMake build directory. This pulls both the Fossil |
|
261
|
CMake-based project and the original Makefiles-based project which appears |
|
262
|
under _[Subprojects]/fossil_ |
|
263
|
1. Do _Build_ and then menu _Project> C/C++ Index: Rebuild_ to pick up the |
|
264
|
generated sources needed for the code browsing and autocomplete |
|
265
|
1. Navigate definitions/implementations. For example, in `src/main.c` |
|
266
|
function `version_cmd()` hover mouse over the call to `fossil_print()` -- |
|
267
|
this allows to peek at its implementation. Or select _Open Declaration_ |
|
268
|
from the context menu. |
|
269
|
1. For running and debugging, create a new _Run:Run Configuration_ for |
|
270
|
_C/C++ Application_; name it `fossil`, pick a project executable |
|
271
|
`bin/fossil` and specify run arguments. For example: `version` |
|
272
|
1. Do _Debug fossil_, which would switch to the Debug perspective and the |
|
273
|
editor opens file `main_.c` (generated!!), execution stops in `main()` |
|
274
|
|
|
275
|
|
|
276
|
> __WARNING__: Edits to _generated_ files in the build directory will __NOT__ |
|
277
|
> survive a _Rebuild_, and the changes cannot be committed directly to the |
|
278
|
> project repository. |
|
279
|
> |
|
280
|
> Make sure you edit files in the Fossil __source__ directories. |
|
281
|
|
|
282
|
|
|
283
|
> __NOTE__: Eclipse creates a few local files and folders to keep its settings, |
|
284
|
> (namely `.project`) which may already be part of Fossil, so make sure not to |
|
285
|
> push them to the main Fossil repository. |
|
286
|
|
|
287
|
|
|
288
|
<a name="cmake-vscode"></a> |
|
289
|
__VSCode__ |
|
290
|
|
|
291
|
If you're a regular VSCode user, you probably have all the needed C/C++ and |
|
292
|
CMake extensions already installed and set up. Otherwise, C/C++ and CMake |
|
293
|
extensions need to be installed from the marketplace to enable CMake support. |
|
294
|
For example: |
|
295
|
|
|
296
|
1. _C/C++_ ("C/C++", ms-vscode.cpptools) |
|
297
|
1. _CMake Tools_ ("CMake Tools") |
|
298
|
1. _CMake_ ("CMake For VisualStudio Code") |
|
299
|
|
|
300
|
Then you may follow the CMake Tools "Getting Started" guide skipping to |
|
301
|
"Configuring Your Project" section. It's also helpful to review "C/C++" |
|
302
|
extension documentation for "Configuring launch.json for C/C++ debugging". |
|
303
|
|
|
304
|
Briefly: |
|
305
|
|
|
306
|
1. Open the Fossil source project folder in VSCode: |
|
307
|
|
|
308
|
cd fossil |
|
309
|
code . |
|
310
|
|
|
311
|
1. _CMake Tools_ extension notification prompts to configure your project |
|
312
|
1. Select a _Kit_ from the shown list. For example, `GCC` |
|
313
|
1. _CMake Tools_ then executes CMake commands and by default configures the |
|
314
|
project to build in `build/` subdirectory with Debug configuration. |
|
315
|
1. In status bar set active target `app` (it's set to `[all]` by default) |
|
316
|
1. Build the project -- status-bar command _Build_ |
|
317
|
1. Navigate definitions/implementations. For example, in `src/main.c` function |
|
318
|
`version_cmd()` for the function `fossil_print()` select context menu |
|
319
|
_Peek Definition_ -- the Fossil source file `src/printf.c` automatically |
|
320
|
opens the peek preview pane. |
|
321
|
1. Set the run arguments -- menu _Debug:Open Configurations_ for C/C++ in the |
|
322
|
file `.vscode/launch.json`. For example, for _"(gdb) Launch"_ configuration |
|
323
|
add: |
|
324
|
|
|
325
|
"program": "${workspaceFolder}/build/bin/fossil", |
|
326
|
"args": ["version"], |
|
327
|
"stopAtEntry": true, |
|
328
|
"cwd": "${workspaceFolder}/build", |
|
329
|
Save the file. |
|
330
|
1. Switch to the Debug view and _Start Debugging_; the editor opens file |
|
331
|
`main_.c` (generated!!), execution stops in `main()` |
|
332
|
|
|
333
|
|
|
334
|
> __WARNING__: Edits to _generated_ files in the build directory will __NOT__ |
|
335
|
> survive a _Rebuild_, and the changes cannot be committed directly to the |
|
336
|
> project repository. |
|
337
|
> |
|
338
|
> Make sure you edit files in the Fossil __source__ directories. |
|
339
|
|
|
340
|
|
|
341
|
<a name="cmake-cb"></a> |
|
342
|
__Code::Blocks__ |
|
343
|
|
|
344
|
1. Create a build directory |
|
345
|
1. Generate the Code::Blocks project from the Fossil `CMakeLists.txt` file: |
|
346
|
|
|
347
|
mkdir build-debug |
|
348
|
cd build-debug |
|
349
|
cmake .. -G"CodeBlocks - Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug |
|
350
|
ls fossil.cbp |
|
351
|
|
|
352
|
1. Open the generated Code::Blocks project `.cbp` file |
|
353
|
1. Select and build `app` target (_Logs_ view shows _Build log_ output) |
|
354
|
1. Re-run the CMake command to refresh the project tree so it shows the |
|
355
|
generated source/include files: |
|
356
|
|
|
357
|
cmake .. |
|
358
|
|
|
359
|
1. Navigate source for definitions/implementations. For example, in `src/main.c` |
|
360
|
function `version_cmd()` find the implementation of `fossil_print()` -- the |
|
361
|
Fossil source file `src/printf.c` automatically opens in editor to show the |
|
362
|
function body. |
|
363
|
1. Set the run arguments -- menu _Project:Set program's arguments_ for target |
|
364
|
`app`. For example: `version` |
|
365
|
1. _Run_; OR |
|
366
|
1. For debugging select Menu _Debug:Step-in_; the editor opens file `main_.c` |
|
367
|
(generated!!), execution stops in `main()` |
|
368
|
|
|
369
|
|
|
370
|
> __WARNING__: Edits to _generated_ files in the build directory will __NOT__ |
|
371
|
> survive a _Rebuild_, and the changes cannot be committed directly to the |
|
372
|
> project repository. |
|
373
|
> |
|
374
|
> Make sure you edit files in the Fossil __source__ directories. |
|
375
|
|
|
376
|
|
|
377
|
<a name="import-makefile"></a> |
|
378
|
Import the Existing Fossil Makefile |
|
379
|
----------------------------------- |
|
380
|
|
|
381
|
Many IDEs allow importing an existing Makefile based project. However, not |
|
382
|
all Makefiles are equally straightforward to import. Fossil's build process |
|
383
|
involves quite extensive use of code-generation, which complicates dependency |
|
384
|
resolution. The resulting IDE project file may turn up not very practical. |
|
385
|
Additionally, such an imported project will need to be maintained manually or |
|
386
|
re-imported to account for upstream updates in the Fossil project (additions, |
|
387
|
renames etc.) |
|
388
|
|
|
389
|
On the plus side, once the resulting Fossil IDE project has been configured, |
|
390
|
it's as close to the original Makefile as it could be. Chances are the bulk of |
|
391
|
dependencies would remain fairly static, as the Fossil project evolution shows. |
|
392
|
|
|
393
|
So far adopting of the Fossil Makefile project has been tried with the |
|
394
|
following IDEs: |
|
395
|
|
|
396
|
* [Eclipse CDT](#import-eclipse) (Linux) |
|
397
|
* [Visual Studio 2017](#import-vs) (Windows) |
|
398
|
|
|
399
|
The general approach for adopting the existing Fossil Makefile into an IDE is |
|
400
|
as follows: |
|
401
|
|
|
402
|
1. Configure the Fossil project to generate the main Makefile (Linux and |
|
403
|
similar) |
|
404
|
|
|
405
|
./configure --fossil-debug |
|
406
|
|
|
407
|
1. Import the existing Makefile project into via IDE's wizard or other |
|
408
|
facility |
|
409
|
1. Try to build the resulting project (to check the dependencies) |
|
410
|
1. Adjust the IDE project settings to resolve missing dependencies |
|
411
|
1. Test the code indexing whether definitions/implementations are resolved |
|
412
|
into correct sources |
|
413
|
1. Create and test the Debug configuration (defined FOSSIL_DEBUG preprocessor |
|
414
|
macro) |
|
415
|
|
|
416
|
Below are the steps used to adopt Fossil Makefile project into the IDEs tested. |
|
417
|
|
|
418
|
|
|
419
|
<a name="import-eclipse"></a> |
|
420
|
__Eclipse CDT__ |
|
421
|
|
|
422
|
A configured Fossil Makefile-based project can be imported __as is__ into |
|
423
|
Eclipse CDT. With a few tweaks, it allows code-browsing, autocomplete, and |
|
424
|
debugging. |
|
425
|
|
|
426
|
1. Configure the Fossil project to generate the main Makefile (Linux and |
|
427
|
similar) |
|
428
|
|
|
429
|
./configure --fossil-debug |
|
430
|
|
|
431
|
1. Do menu _File> Import> C/C++: Existing Code as Makefile Project_ |
|
432
|
1. Browse to the Fossil project directory |
|
433
|
1. Pick the configured Toolchain, e.g. `Linux GCC` |
|
434
|
1. Once the import completed, the source tree is populated with source |
|
435
|
directories. At this point the project is already _buildable_, yet source |
|
436
|
browsing is not fully functional yet. Add the following settings: |
|
437
|
1. Do Menu _Project> Properties> C/C++ General: Paths and Symbols_ |
|
438
|
1. Add _Includes_ in workspace folders: `fossil/bld`, `fossil/src` |
|
439
|
1. Add _Output Location_: `fossil/bld` |
|
440
|
1. Do _Build_ and then menu _Project> C/C++ Index: Rebuild_ to pick up the |
|
441
|
generated sources needed for the code browsing and autocomplete |
|
442
|
1. Navigate definitions/implementations. For example, in `src/main.c` function |
|
443
|
`version_cmd()` hover mouse over the call to `fossil_print()` -- this allows |
|
444
|
to peek at its implementation. Or select _Open Declaration_ from the context |
|
445
|
menu. |
|
446
|
1. For running and debugging, create a new _Run:Run Configuration_ for |
|
447
|
_C/C++ Application_; name it `fossil`, pick a project executable `bin/fossil` |
|
448
|
and specify run arguments. For example: `version` |
|
449
|
1. Do _Debug fossil_, which would switch to the Debug perspective and the editor |
|
450
|
opens file `main_.c` (generated!!), execution stops in `main()` |
|
451
|
|
|
452
|
|
|
453
|
> __WARNING__: Edits to _generated_ files in the build directory will __NOT__ |
|
454
|
> survive a _Rebuild_, and the changes cannot be committed directly to the |
|
455
|
> project repository. |
|
456
|
> |
|
457
|
> Make sure you edit files in the Fossil __source__ directories. |
|
458
|
|
|
459
|
|
|
460
|
> __NOTE__: Eclipse creates a few local files and folders to keep its settings, |
|
461
|
> (namely `.project`) which may already be part of Fossil, so make sure not to |
|
462
|
> push them to the main Fossil repository. |
|
463
|
|
|
464
|
|
|
465
|
<a name="import-vs"></a> |
|
466
|
__Visual Studio 2017__ |
|
467
|
|
|
468
|
There're several ways of how to layout an imported project, here we show a |
|
469
|
straightforward way that makes use of Visual Studio's import wizard. |
|
470
|
|
|
471
|
|
|
472
|
> __NOTE__: In such a layout, the build directory `msvcbld` is shared between |
|
473
|
> the build configurations. This requires a clean re-build when switching the |
|
474
|
> build configuration or target platform in case of cross-compiling. |
|
475
|
|
|
476
|
|
|
477
|
1. Menu _File> New> Project From Existing Code_; a wizard starts |
|
478
|
|
|
479
|
Project Type: Visual C++ |
|
480
|
Project file location: <Fossil project source directory> |
|
481
|
Project name: fossil |
|
482
|
Folders: |
|
483
|
src/ (Add subfolders: Yes) |
|
484
|
win/ (Add subfolders: Yes) |
|
485
|
|
|
486
|
Project Settings: Use external build system |
|
487
|
|
|
488
|
Build command line (Debug): win\buildmsvc.bat FOSSIL_DEBUG=1 |
|
489
|
Rebuild All command line (Debug): |
|
490
|
Clean command line (Debug): win\buildmsvc.bat FOSSIL_DEBUG=1 clean clean-zlib |
|
491
|
Output (Debug): msvcbld\fossil.exe |
|
492
|
Preprocessor definitions (Debug): |
|
493
|
Include Search Path (Debug): msvcbld;src;.;compat/zlib |
|
494
|
|
|
495
|
Build command line (Debug): win\buildmsvc.bat |
|
496
|
Rebuild All command line (Debug): |
|
497
|
Clean command line (Debug): win\buildmsvc.bat clean clean-zlib |
|
498
|
Output (Debug): msvcbld\fossil.exe |
|
499
|
Preprocessor definitions (Debug): |
|
500
|
Include Search Path (Debug): msvcbld;src;.;compat/zlib |
|
501
|
Apply the settings. |
|
502
|
1. New solution file `fossil.sln` and project file `fossil.vcxproj` are |
|
503
|
created in the Fossil project source directory |
|
504
|
1. Change the project build directory to `msvcbld` for All Configurations and |
|
505
|
All Platforms -- menu _Project> fossil Properties> General__ |
|
506
|
|
|
507
|
Output Directory: $(SolutionDir)mscvcbld\ |
|
508
|
Intermediate Directory: mscvcbld\ |
|
509
|
Build Log File: $(IntDir)$(MSBuildProjectName)-$(Configuration).log |
|
510
|
|
|
511
|
1. Select a target build configuration -- toolbar _Solution Configurations_, |
|
512
|
and _Solution Platforms_ (For example, `Debug`, `x64`) |
|
513
|
1. Do menu _Build> Build Solution_ |
|
514
|
1. Navigate definitions/implementations. For example, in `src/main.c` |
|
515
|
function `version_cmd()` for the function `fossil_print()` select |
|
516
|
context menu _Peek Definition_ -- the Fossil source file `src/printf.c` |
|
517
|
automatically opens the peek preview pane. |
|
518
|
1. Set the run arguments -- menu _Project> fossil Properties: Debugging: |
|
519
|
Command arguments_. For example: `version` |
|
520
|
1. To start debugging -- do menu _Debug> Step Into_; the editor opens file |
|
521
|
`main_.c` (generated!!), execution stops in `main()`. |
|
522
|
1. Before switching to another build configuration, do menu |
|
523
|
_Build> Clean Solution_; then switch and build. |
|
524
|
|
|
525
|
|
|
526
|
> __WARNING__: Edits to _generated_ files in the build directory will __NOT__ |
|
527
|
> survive a _Rebuild_, and the changes cannot be committed directly to the |
|
528
|
> project repository. |
|
529
|
> |
|
530
|
> Make sure you edit files in the Fossil __source__ directories. |
|
531
|
|
|
532
|
|
|
533
|
<a name="see-also"></a> |
|
534
|
See Also |
|
535
|
-------- |
|
536
|
|
|
537
|
* [Adding Features to Fossil](./adding_code.wiki) |
|
538
|
* [The Fossil Build Process](./makefile.wiki) |
|
539
|
|