| | @@ -0,0 +1,538 @@ |
| 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)
|