Fossil

Overview

IDE is not required to build Fossil. However, IDE may be useful in development of the Fossil code. Staple IDE features that come to mind are ease of editing, static code analysis, source indexing, autocomplete, and integrated debugging.

Who may benefit from using an IDE? In general sense, of course, anyone who is used to a particular IDE. Specifically to Fossil development this could be:

• Developers who are new to Fossil code; IDE helps navigate definitions and implementations across the source files

• Developers who may be familiar with the code, yet would want to diagnose an issue that calls for in-depth debugging; IDE makes debugging somewhat more accessible

Current Fossil build process is Makefile-based, which extensively uses code-generation. It's flexible, yet as such it's not natively fitting any specific IDE. This often represents a challenge for an IDE workflow as it's trying to figure out the correct dependencies.

To assist with Fossil IDE workflow, there're currently two alternatives to consider depending on IDE capabilities to support it:

• Use CMake-based workflow; in this case the Fossil's CMakeLists.txt file is directly used as the IDE project file

• Import the existing Makefile and then tweak the resulting project settings to properly reference the dependencies

The following sections describe both approaches as tested with a selection of IDEs (not exhaustive).

USAGE NOTES: To get most utility out of IDE in Fossil development, it's recommended to do a general development in Release build configuration. In this case, compile errors would refer to original source files instead of the generated ones which actually get compiled. Clicking on such error message in the IDE output pane will bring up the source file and the offending line.

This somewhat reduces chances of making edits in the generated files just to see the precious code lost as the files get re-generated during build.

Switch to Debug build configuration once in a need to chase that bug that is playing hard to get. The debugger is stepping through the actually compiled code, that is the editor will load the generated files from the build directory. While fixing the bugs, just be aware of where to make the edits.

A simple rule of thumb is to keep only <module>.c source files open, closing the files <module>_.c (underscored) and <module>.h (header) which get generated in the build directory.

WARNING: Edits to generated files in the build directory will NOT survive a Rebuild, and the changes cannot be committed directly to the project repository.

Make sure you edit files in the Fossil source directories.

CMake-based Fossil Workflow

Most major C/C++ IDEs handle CMake projects either natively or via native project files generated from the given CMakeLists.txt.

So far the Fossil CMake-based workflow has been tried with the following IDEs:

• Qt Creator (Linux, Windows)
• VisualStudio 2017 (Windows)
• Eclipse CDT (Linux)
• VSCode (Linux, Windows)
• Code::Blocks (Linux)

Using CMake on the Command-line

In general, the CMake workflow is very much the same on all of the supported platforms. CMake generator takes care of the platform/compiler specifics.

CMake can be used directly on the command-line to build the Fossil project in either Release or Debug configuration:

cd fossil
mkdir build-debug
cd build-debug
cmake .. -G"Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug
make

OR on Windows with MSVC:

cmake .. -G"NMake Makefiles" -DCMAKE_BUILD_TYPE=Debug
nmake

An IDE executes similar commands behind the scenes to generate and build a CMake-based project. In general, CMake is capable of generating native project files for a wide selection of IDEs. However for the Fossil CMake project, it's preferable to generate a Makefiles build system, because that's what the underlying Fossil build process is.

Below are the steps used to setup Fossil CMake project in the IDEs tested.

NOTE: To refresh a Project Tree View so that it shows the generated files, the easiest way is to re-save the CMakeLists.txt file. This triggers the IDE tools to regenerate the build system and rescan the project source files.

Qt Creator

CMake workflow in Qt Creator has been supported for quite some time, so it evolved to become more streamlined. Below are the steps to set up CMake project in Qt Creator version 4.5 and above.

1. From Weclome panel Open Project, browse to the Fossil project directory and open the CMakeLists.txt file.
2. Qt Creator will prompt to select a Kit to configure the project. For example, Desktop Qt 5.9.4 GCC 64bit

At this point the project is already usable. Optionally, for convenience it makes sense to adjust some of the default settings.

1. Open the Projects panel
2. Remove the extra build configurations, keep Debug and Release

3. For each of the build configurations

   • Select a Build directory. For example: build-fossil-debug/ directory or build-debug/ subdirectory.
   • Set any additional CMake variables

Now it's ready for build and use.

1. Select the build configuration; for example Debug
2. Do Build Project "fossil"; it runs the CMake and then starts the build showing the progress in the Compile Output pane

3. Refresh the Projects Explorer View so that it shows the generated files:

   • Open the CMakeLists.txt file and trivially "touch" it then re-save it.
   • This triggers CMake which then re-populates the Project Explorer View adding the generated header files from the build directory.

4. Navigate definitions/implementations. For example, in src/main.c function version_cmd() for the function fossil_print() select context menu Follow Symbol Under Cursor -- the Fossil source file src/printf.c automatically opens in editor.

5. Set the run arguments -- panel Projects: Run; by default the app target is already selected (bin/fossil executable):

   • Set the Command line arguments: for example, version
   • Optionally, check Run in terminal

6. Do Run OR

7. To start debugging -- do menu Debug> Step Into; the editor opens file main_.c (generated!!), execution stops in main(). Fossil executable output is shown in a separate terminal window.

WARNING: Edits to generated files in the build directory will NOT survive a Rebuild, and the changes cannot be committed directly to the project repository.

Make sure you edit files in the Fossil source directories.

Visual Studio 2017

Starting with Visual Studio 2017 CMake-based projects (CMakeLists.txt files) are directly supported without the need to generate an intermediate MSBuild project files. This feature is supported via Visual C++ Tools for CMake component which is installed by default as part of the Desktop development with C++ workload.

NOTE: By default, Visual Studio 2017 CMake Tools uses Ninja build tool. In general it has a better performance over the usual NMake, as it allows parallel build tasks. However in the scope of Fossil CMake project there's no real speedup, since the underlying Fossil Makefile is still built with NMake.

As Ninja tool has some subtle differences in handling of the clean target, it's recommended to select the "NMake Makefiles" generator for the Fossil CMake project (which is a valid choice despite a possible warning.)

1. Menu File> Open:Folder to open Fossil source project directory that contains the CMakeLists.txt file

2. Change the generator -- menu CMake> Change CMake Settings> fossil will open CMakeSettings.json file; in all of the defined configurations set:

   "generator": "NMake Makefiles",
   "buildCommandArgs": "",
   

   Save the settings file and the project is reconfigured automatically.

3. Select configuration -- toolbar Select Project Settings, for example: x64-Debug

4. Do menu CMake> Build All; build progress is shown in Output:Build pane

5. Navigate definitions/implementations. For example, in src/main.c function version_cmd() for the function fossil_print() select context menu Peek Definition -- the Fossil source file src/printf.c automatically opens the peek preview pane.

6. Select a start target bin/fossil.exe -- toolbar Select Startup Item

7. Set the run arguments -- menu CMake> Debug and Launch Settings in the file .vs/launch.vs.json. For example, for "default" configuration append:

   "args": ["version"]
   

   Save the settings file.

8. To start debugging -- do menu Debug> Step Into; the editor opens file main_.c (generated!!), execution stops in main(). Fossil executable output is shown in a separate terminal window.

WARNING: Edits to generated files in the build directory will NOT survive a Rebuild, and the changes cannot be committed directly to the project repository.

Make sure you edit files in the Fossil source directories.

NOTE: If doing a cross-platform build, it's necessary to clean the builds of the external components that are used with Fossil (in compat/ subdirectory). For example, zlib, openssl. Failure to do that may manifest with the fireworks of compile and link errors.

Eclipse CDT

To configure CMake-based project with Eclipse it first has to be generated as a native project, then imported into Eclipse as an existing project.

The CMake build directory should not be a subdirectory of the Fossil project source directory, but rather a sibling or other directory. For example:

workspace/
|-- fossil-debug/              <== CMake build directory
|-- fossil/                    <== Fossil project directory
|   `-- CMakeLists.txt
`-- fossil-release/

1. Generate Eclipse CDT4 makefiles, optionally specify the Eclipse's version:

   cd workspace
   cd debug
   cmake ../fossil -G"Eclipse CDT4 - Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug
        -DCMAKE_ECLIPSE_VERSION=3.8
   ls .cproject
   

2. From Eclipse do Import as a General>Existing Projects into Workspace from within the CMake build directory. This pulls both the Fossil CMake-based project and the original Makefiles-based project which appears under [Subprojects]/fossil

3. Do Build and then menu Project> C/C++ Index: Rebuild to pick up the generated sources needed for the code browsing and autocomplete

4. Navigate definitions/implementations. For example, in src/main.c function version_cmd() hover mouse over the call to fossil_print() -- this allows to peek at its implementation. Or select Open Declaration from the context menu.

5. For running and debugging, create a new Run:Run Configuration for C/C++ Application; name it fossil, pick a project executable bin/fossil and specify run arguments. For example: version

6. Do Debug fossil, which would switch to the Debug perspective and the editor opens file main_.c (generated!!), execution stops in main()

WARNING: Edits to generated files in the build directory will NOT survive a Rebuild, and the changes cannot be committed directly to the project repository.

Make sure you edit files in the Fossil source directories.

NOTE: Eclipse creates a few local files and folders to keep its settings, (namely .project) which may already be part of Fossil, so make sure not to push them to the main Fossil repository.

VSCode

If you're a regular VSCode user, you probably have all the needed C/C++ and CMake extensions already installed and set up. Otherwise, C/C++ and CMake extensions need to be installed from the marketplace to enable CMake support. For example:

1. C/C++ ("C/C++", ms-vscode.cpptools)
2. CMake Tools ("CMake Tools")
3. CMake ("CMake For VisualStudio Code")

Then you may follow the CMake Tools "Getting Started" guide skipping to "Configuring Your Project" section. It's also helpful to review "C/C++" extension documentation for "Configuring launch.json for C/C++ debugging".

Briefly:

1. Open the Fossil source project folder in VSCode:

   cd fossil
   code .
   

2. CMake Tools extension notification prompts to configure your project

3. Select a Kit from the shown list. For example, GCC

4. CMake Tools then executes CMake commands and by default configures the project to build in build/ subdirectory with Debug configuration.

5. In status bar set active target app (it's set to [all] by default)

6. Build the project -- status-bar command Build

7. Navigate definitions/implementations. For example, in src/main.c function version_cmd() for the function fossil_print() select context menu Peek Definition -- the Fossil source file src/printf.c automatically opens the peek preview pane.

8. Set the run arguments -- menu Debug:Open Configurations for C/C++ in the file .vscode/launch.json. For example, for "(gdb) Launch" configuration add:

   "program": "${workspaceFolder}/build/bin/fossil",
   "args": ["version"],
   "stopAtEntry": true,
   "cwd": "${workspaceFolder}/build",
   

   Save the file.

9. Switch to the Debug view and Start Debugging; the editor opens file main_.c (generated!!), execution stops in main()

WARNING: Edits to generated files in the build directory will NOT survive a Rebuild, and the changes cannot be committed directly to the project repository.

Make sure you edit files in the Fossil source directories.

Code::Blocks

1. Create a build directory

2. Generate the Code::Blocks project from the Fossil CMakeLists.txt file:

   mkdir build-debug
   cd build-debug
   cmake .. -G"CodeBlocks - Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug
   ls fossil.cbp
   

3. Open the generated Code::Blocks project .cbp file

4. Select and build app target (Logs view shows Build log output)

5. Re-run the CMake command to refresh the project tree so it shows the generated source/include files:

   cmake ..
   

6. Navigate source for definitions/implementations. For example, in src/main.c function version_cmd() find the implementation of fossil_print() -- the Fossil source file src/printf.c automatically opens in editor to show the function body.

7. Set the run arguments -- menu Project:Set program's arguments for target app. For example: version

8. Run; OR

9. For debugging select Menu Debug:Step-in; the editor opens file main_.c (generated!!), execution stops in main()

WARNING: Edits to generated files in the build directory will NOT survive a Rebuild, and the changes cannot be committed directly to the project repository.

Make sure you edit files in the Fossil source directories.

Import the Existing Fossil Makefile

Many IDEs allow importing an existing Makefile based project. However, not all Makefiles are equally straightforward to import. Fossil's build process involves quite extensive use of code-generation, which complicates dependency resolution. The resulting IDE project file may turn up not very practical. Additionally, such an imported project will need to be maintained manually or re-imported to account for upstream updates in the Fossil project (additions, renames etc.)

On the plus side, once the resulting Fossil IDE project has been configured, it's as close to the original Makefile as it could be. Chances are the bulk of dependencies would remain fairly static, as the Fossil project evolution shows.

So far adopting of the Fossil Makefile project has been tried with the following IDEs:

• Eclipse CDT (Linux)
• Visual Studio 2017 (Windows)

The general approach for adopting the existing Fossil Makefile into an IDE is as follows:

1. Configure the Fossil project to generate the main Makefile (Linux and similar)

   ./configure --fossil-debug
   

2. Import the existing Makefile project into via IDE's wizard or other facility

3. Try to build the resulting project (to check the dependencies)

4. Adjust the IDE project settings to resolve missing dependencies

5. Test the code indexing whether definitions/implementations are resolved into correct sources

6. Create and test the Debug configuration (defined FOSSIL_DEBUG preprocessor macro)

Below are the steps used to adopt Fossil Makefile project into the IDEs tested.

Eclipse CDT

A configured Fossil Makefile-based project can be imported as is into Eclipse CDT. With a few tweaks, it allows code-browsing, autocomplete, and debugging.

1. Configure the Fossil project to generate the main Makefile (Linux and similar)

   ./configure --fossil-debug
   

2. Do menu File> Import> C/C++: Existing Code as Makefile Project

3. Browse to the Fossil project directory

4. Pick the configured Toolchain, e.g. Linux GCC

5. Once the import completed, the source tree is populated with source directories. At this point the project is already buildable, yet source browsing is not fully functional yet. Add the following settings:

6. Do Menu Project> Properties> C/C++ General: Paths and Symbols

7. Add Includes in workspace folders: fossil/bld, fossil/src

8. Add Output Location: fossil/bld

9. Do Build and then menu Project> C/C++ Index: Rebuild to pick up the generated sources needed for the code browsing and autocomplete

10. Navigate definitions/implementations. For example, in src/main.c function version_cmd() hover mouse over the call to fossil_print() -- this allows to peek at its implementation. Or select Open Declaration from the context menu.

11. For running and debugging, create a new Run:Run Configuration for C/C++ Application; name it fossil, pick a project executable bin/fossil and specify run arguments. For example: version

12. Do Debug fossil, which would switch to the Debug perspective and the editor opens file main_.c (generated!!), execution stops in main()

WARNING: Edits to generated files in the build directory will NOT survive a Rebuild, and the changes cannot be committed directly to the project repository.

Make sure you edit files in the Fossil source directories.

NOTE: Eclipse creates a few local files and folders to keep its settings, (namely .project) which may already be part of Fossil, so make sure not to push them to the main Fossil repository.

Visual Studio 2017

There're several ways of how to layout an imported project, here we show a straightforward way that makes use of Visual Studio's import wizard.

NOTE: In such a layout, the build directory msvcbld is shared between the build configurations. This requires a clean re-build when switching the build configuration or target platform in case of cross-compiling.

1. Menu File> New> Project From Existing Code; a wizard starts

   Project Type: Visual C++
   Project file location: <Fossil project source directory>
   Project name: fossil
   Folders:
       src/ (Add subfolders: Yes)
       win/ (Add subfolders: Yes)
   
   Project Settings: Use external build system
   
   Build command line (Debug): win\buildmsvc.bat FOSSIL_DEBUG=1
   Rebuild All command line (Debug):
   Clean command line (Debug): win\buildmsvc.bat FOSSIL_DEBUG=1 clean clean-zlib
   Output (Debug): msvcbld\fossil.exe
   Preprocessor definitions (Debug):
   Include Search Path (Debug): msvcbld;src;.;compat/zlib
   
   Build command line (Debug): win\buildmsvc.bat
   Rebuild All command line (Debug):
   Clean command line (Debug): win\buildmsvc.bat clean clean-zlib
   Output (Debug): msvcbld\fossil.exe
   Preprocessor definitions (Debug):
   Include Search Path (Debug): msvcbld;src;.;compat/zlib
   

   Apply the settings.

2. New solution file fossil.sln and project file fossil.vcxproj are created in the Fossil project source directory

3. Change the project build directory to msvcbld for All Configurations and All Platforms -- menu _Project> fossil Properties> General__

   Output Directory:  $(SolutionDir)mscvcbld\
   Intermediate Directory:  mscvcbld\
   Build Log File:  $(IntDir)$(MSBuildProjectName)-$(Configuration).log
   

4. Select a target build configuration -- toolbar Solution Configurations, and Solution Platforms (For example, Debug, x64)

5. Do menu Build> Build Solution

6. Navigate definitions/implementations. For example, in src/main.c function version_cmd() for the function fossil_print() select context menu Peek Definition -- the Fossil source file src/printf.c automatically opens the peek preview pane.

7. Set the run arguments -- menu Project> fossil Properties: Debugging: Command arguments. For example: version

8. To start debugging -- do menu Debug> Step Into; the editor opens file main_.c (generated!!), execution stops in main().

9. Before switching to another build configuration, do menu Build> Clean Solution; then switch and build.

WARNING: Edits to generated files in the build directory will NOT survive a Rebuild, and the changes cannot be committed directly to the project repository.

Make sure you edit files in the Fossil source directories.

See Also

• Adding Features to Fossil
• The Fossil Build Process