qtcreator-plugin-fossil: Fossil SCM plugin for Qt Creator {#main}

Overview

qtcreator-plugin-fossil is a version control plugin for Qt Creator
IDE. It implements support for fossil SCM, which is a free and
open-source distributed version control system (DVCS) and as such it adds to the
same toolbox as git, Bazaar, Mercurial etc.

fossil SCM is designed and developed by D. Richard Hipp, the creator of
SQLite; in fact, the official repository for
SQLite source code is managed with fossil, so is its own.
Some highlights of fossil SCM: it’s lightweight (just a single stand-alone
executable), it presents an intuitive yet potent command-line interface, it
yields a reasonable performance as one may expect from SQLite (fossil uses
it internally), it includes a built-in HTTP-server. On top of this, it also
features a built-in web-interface, issue-tracking, and project-wiki pages
… it also fixes bugs in your code on check-in (no, it doesn’t — but it
fossilizes them for posterity :)

Most importantly, fossil is portable and available on the mainstream platforms.
In a way, fossil offers to version control, what SQLite does to
database realm, making it easy to introduce version control practices to teams
and projects of any size. In any case, we needed to make our existing fossil
repositories work with Qt Creator — so here it is.

qtcreator-plugin-fossil is built with Qt Creator VCS framework (similar
to official Bazaar plugin) and makes use of fossil command-line interface.
This directly integrates fossil into Qt Creator project flow. It supports
base set of version control operations (excluding merge). The guiding intent is
not to provide a full-blown GUI client to fossil (it has its web-interface
already), but to marry the IDE convenience with the general version control flow.

qtcreator-plugin-fossil is a free software; the use, copy, and distribution
rights are granted under the terms of the
@ref qtc-fossil-license | MIT License.

Features

qtcreator-plugin-fossil directly integrates fossil into Qt Creator project
flow similarly to git and Bazaar. It supports base set of version control
operations:

create local fossil repository
clone a remote fossil repository
add/delete/rename tracked files
show current status of the repository and current files
commit changes made (branch and tag on commit)
show timeline of the commits
annotate file source lines with respective check-ins
diff changes
check-out/revert files in given revision
push/pull/update changes to/from remote repository

This covers routine operations in code development context (stashing would
be nice too, well, maybe in the future). The rest (repository management, merge,
etc.) could be achieved via fossil command-line or web-interface.

Refer to “Using Version Control Systems” Qt Creator help page for more
details.

Updates and details about the current version listed in
@ref qtc-fossil-changelog | qtcreator-plugin-fossil ChangeLog.

Quick Start

The recent releases of qtcreator-plugin-fossil are available already pre-
built for the supported platforms, thanks to the GitHub’s CI workflow features.
This greatly simplifies the availability and installation of the plugin.

To install the qtcreator-plugin-fossil for Qt Creator version 4.11 and
higher, you may download the binary release package from the project’s
Releases GtHub page.

The packages are prepared for direct integration of the Fossil plugin into
an existing Qt Creator installation and consist of the plugin library file
and an updated Qt Creator documentation (.qch) file.

In brief, the plugin’s 7z-package could be extracted directly into the
Qt Creator installation directory. For example, plugin’s ver=4.11.2_2
built for Qt Creator version 4.11.2 (compatible with 4.11.0 and higher
patch-releases):

 7z x QtCreator-Fossil-${ver}-Linux-x64.7z -o"${qtc_dir}" '-x!README.md'

Alternatively, the qtcreator-plugin-fossil library file could be installed
as a user-plugin, locally to the user’s home directory. Please refer to the
README.md file included in the release installation package for details.

Building from Sources

In short, it’s a Qt Creator plugin, so those familiar with plugin building
may just skip through to fetch the sources. Otherwise, read on.

As with any Qt Creator plugins, qtcreator-plugin-fossil sources need to be
integrated into Qt Creator source tree, then built as part of Qt Creator
build process. Thus the plugin sources must target a specific Qt Creator
version. In the course of the qtcreator-plugin-fossil project we naturally
adapted it for selected Qt Creator updates, mostly targeting the long-term
support versions. It may be possible to try building it with interim releases,
though some tweaking may be needed to account for the underlying VCS framework
changes.

So the Quick start is not that quick as it requires some preparations and, yes,
the full Qt Creator build, before the qtcreator-plugin-fossil library could
be harvested and installed for use with the existing Qt Creator instance of
matching or compatible version.

For reference: official instructions on how to
build Qt Creator from sources, also see Qt Creator own
README.

In our experience, we normally would already have an active Qt Creator instance
(from Qt SDK installation), and would fetch the sources for that version, then
use that instance to build another one from sources with the
qtcreator-plugin-fossil integrated. This leverages the IDE to help track
possible wrinkles (mostly missing dependencies) or source incompatibilities.

Cloning Qt Creator repository is ok too, but be ready to accept over 250MB of
its size. Alternatively, this repository contains forks for selected
Qt Creator releases with qtcreator-plugin-fossil sources integrated
(see qtcreator-fossil-* branches, subject to Qt Creator license). We used these
directly to build and test qtcreator-plugin-fossil.

Fetch the Qt Creator sources for the needed ${version} either from official git
repository; optionally fetch the sources for the qbs module ${qbs_version}

  wget --output-document qt-creator-${version}.tar.gz https://github.com/qtproject/qt-creator/archive/v${version}.tar.gz
  wget --output-document qt-creator-${version}-qbs.tar.gz https://github.com/qt-labs/qbs/archive/v${qbs_version}.tar.gz

Fetch the qtcreator-plugin-fossil sources for the matching version ${plugin_fossil_version}

  wget --output-document qt-creator-${version}-fossil.tar.gz https://github.com/nomadbyte/qtcreator-plugin-fossil/archive/v${plugin_fossil_version}.tar.gz

Merge source trees

  mkdir qtcreator-fossil-${version}
  cd qtcreator-fossil-${version}
  tar xvf ../qt-creator-${version}.tar.gz  --strip-components=1
  tar xvf ../qt-creator-${version}-qbs.tar.gz  --strip-components=1 -C src/shared/qbs/
  tar xvf ../qt-creator-${version}-fossil.tar.gz  --strip-components=1

OR
Fetch the Qt Creator sources with integrated qtcreator-plugin-fossil

  wget --output-document qtcreator-fossil-${version}.tar.gz https://github.com/nomadbyte/qtcreator-plugin-fossil/archive/qtcreator-fossil-${version}.tar.gz
  mkdir qtcreator-fossil-${version}
  cd qtcreator-fossil-${version}
  tar xvf ../qtcreator-fossil-${version}.tar.gz  --strip-components=1

Launch the installed Qt Creator instance and open the qtcreator.pro project
```
  qtcreator-fossil-${version}/qtcreator.pro
```

The integrated qtcreator-plugin-fossil project

  qtcreator-fossil-${version}/src/plugins/fossil/fossil.pro

Build the Qt Creator in Release configuration with your selected Kit

This assumes all needed dependencies are installed

It will take ~some~ time… There will likely be a few warnings in Issues pane.
Once have got successful green build — it should be ready to launch.

In mode:Projects>Run configuration add run parameters to avoid messing up
settings of your active Qt Creator instance. Create these directories
```
  Working dir: <build-dir>/work
  Parameters: -settingspath ../settings
```

Run the built Qt Creator instance and confirm the presence of the Fossil
plugin

  menu:Help>About Plugins..>Version Control::Fossil
  menu:Tools>Options>Version Control::Fossil

Download fossil SCM client and install fossil executable file
in your PATH
Create a directory for local fossil repositories and remote clones
```
  mkdir ~/fossils/qt
```

Configure the qtcreator-plugin-fossil to use that directory

  menu:Tools>Options>Version Control:Local Repositories Default path

Now you should be able to use fossil repositories with Qt Creator

Create a new project and from wizard select Fossil as Version Control

Once the project opens, you should be able to use fossil from the main menu

  menu:Tools>Fossil::Status
  menu:Tools>Fossil::Commit
  menu:Tools>Fossil::Timeline

The newly created fossil repository should also be found in the configured
location. As expected, the newly created project may also be managed via fossil
SCM command-line:

  ls ~/fossils/qt/<new-project>.fossil
  cd <new-project-dir>
  fossil status

As a side-note, fossil already offers ways of sharing the repositories with
other users (see fossil server command), however as an alternative way to host
and serve your fossil repositories, check out
Chisel Fossil SCM Hosting.

To clone a remote project repository, say, hosted at http://chiselapp.com

  menu:File>New File or Project...>Import Project::Fossil Clone
  wizard:Fossil Clone>Remote Repository Clone
  Remote Repository: https://<repouser>:<passwd>@chiselapp.com/user/<username>/repository/<reponame>

NOTE: To use an external fossil repository, it needs to contain a valid
Qt Creator project (.pro) file, which Qt Creator then loads in at clone
completion.

Refer to “Using Version Control Systems” Qt Creator help page for more
details.

Installation

Once the qtcreator-plugin-fossil has been successfully built, it may be
harvested from the build directory to install it for use with your active
Qt Creator instance. Alternatively, install the newly built Qt Creator (refer
to Qt Creator own README)

NOTE: Exit the installed Qt Creator instance, if currently running, prior
to installing the built qtcreator-plugin-fossil. Otherwise Qt Creator may
hang on exiting.

Harvest the built qtcreator-plugin-fossil plugin files from Qt Creator
build directory.
Copy these files to location of the installed Qt Creator instance

On Linux:

  sudo cp $QTC_BUILD_DIR/lib/qtcreator/plugins/*Fossil*  $QTC_INSTALL_DIR/lib/qtcreator/plugins/
  ## for versions prior to v4.3.0_1
  sudo cp -R $QTC_BUILD_DIR/share/qtcreator/templates/wizards/projects/vcs/fossil  $QTC_INSTALL_DIR/share/qtcreator/templates/wizards/projects/vcs/

Optionally install the updated documentation

  cd $QTC_BUILD_DIR
  make docs
  sudo mv $QTC_INSTALLL_DIR/share/doc/qtcreator/qtcreator.qch $QTC_INSTALLL_DIR/share/doc/qtcreator/qtcreator.qch-fossil-uninstall
  sudo cp $QTC_BUILD_DIR/share/doc/qtcreator/qtcreator.qch $QTC_INSTALLL_DIR/share/doc/qtcreator/

Starting up Qt Creator should load the installed qtcreator-plugin-fossil.

NOTE: In case the qtcreator-plugin-fossil fails to load into the
Qt Creator, make sure that it was built with that Qt Creator source version
AND compiler version (see menu:Help>About Qt Creator...).

Usage

Refer to “Using Version Control Systems” Qt Creator help page for more
details.

Support

qtcreator-plugin-fossil has already gone through a number of iterations to keep
up with Qt Creator updates. Qt Creator VCS framework too got its share of
updates, though for the most part it remains stable. Other VCS plugins, already
included in official Qt Creator releases, are based on that framework
(Bazaar plugin, Mercurial plugin etc.) We intend to continue our practice of
maintaining qtcreator-plugin-fossil so that it works with upcoming long-term
support Qt Creator releases. There is obviously a great benefit of having it
also included in the official Qt Creator code base, if that would be deemed
possible.

Let us know of your experience, challenges or problems (bugs?) with it — quite
possible we have dealt with these too and may have work-arounds or may suggest
some alternatives.

Please direct your feedback to
qtcreator-plugin-fossil GitHub project page.

Your contribution is welcomed!