DEVELOPER-INFO.md

Developer Info

Development Software Requirements

Required tools

• OS: Windows 10
• .NET 4.8, .NET 5.0 and .NET Core 3.1
• Visual Studio 2019 with .NET desktop development workload.

  • install the .NET SDK for .NET 4.8, .NET 5.0 and .NET Core 3.1, as available here: https://dotnet.microsoft.com/download

    You'll need all three of 'em as many projects are compiled to all three targets and this spares you from build errors due to missing target environments.

• git or git for Windows
• bash (comes as part of git packages)
• node (NodeJS) & npm (NodeJS Package Manager) —— preferrably installed via nvm for windows

Suggested tools

• TortoiseGIT — UI for git
• Beyond Compare — visual comparison tool, invoked by the Unit and System Tests ApprovalTests framework.
• Syncfusion Essential Studio 17 — the required redistributable binaries are already available in /libs/, needed only if you wish to upgrade SyncFusion libraries.

  Commercial Qiqqa uses SyncFusion v14 and the upgrade to v17 fixed one very annoying bug in Qiqqa's handling of (broken!) PDF files which are already part of your Qiqqa libraries. SyncFusion v17 isn't the bee knees in PDF processing either, so another upgrade might be in order one day...

Building Qiqqa From Source

1. Get the source code from GitHub

To fetch whole repository find Git Bash from Windows' start menu and run:

git clone https://github.com/jimmejardine/qiqqa-open-source.git
cd qiqqa-open-source

Or alternatively just download the source code .zip file.

2. Enable Long Filename Support in git

While still in the qiqqa-open-source folder, run these commands:

git config core.longpaths true
git reset --hard

This is needed because the repository includes "Windows Long Filenames" (at least since commit 0cf15c0d). See StackOverflow.

3. Install required / optional git submodules

Qiqqa uses several libraries and tools which are managed in separate git repositories (see the .gitmodules file).

Install/unpack the minimum required set using:

git submodule update --init

Note: for the full source tree, including MuPDF-based tools and experimental research material, you should invoke

git submodule update --init --recursive

Be aware that this will take a long time to download and install all source code libraries and may consume a serious chunk of your disk space, particularly when you then go and compile/run the various libraries and tools in the MuPDF tree: the Visual Studio 2019 solution and project files will automatically copy the Tesseract data set (1+ GByte) to each binary target directory for ease of use & debugging. As you can build MuPDF in Debug and Release mode for 32 bit and 64 bit targets, that automatic action alone will account for an extra 5-6 Gbyte of disk space.

However, the benefit of this approach would be far fewer surprises during initial build of the entire source tree as you won't have to selectively git submodule update --init install/unpack any git submodules for your build to succeed.

4. Install required tools with npm

While still in the same folder, now run:

npm i

This will set up the Node/npm package environment for the JavaScript/NodeJS based bash scripts which help build Qiqqa. See below.

5. Build Qiqqa

• Open qiqqa-open-source/Qiqqa.sln file to open the project with Visual Studio 2019.

• Choose Release+SETUP solution on top toolbar (there are three different solutions: Debug, Release, Release+SETUP).

• To build Qiqqa, in Build menu click on Build Solution or Rebuild Solution. This should take a while.

• Find setup.exe file in folder qiqqa-open-source/Qiqqa.Build/Packages/v82 - 20200426-212303 or similar. Done.

  The number will be vNN-YYYYMMDD-HHMMSS version+date of the build. The exact path is also listed at the end of the Output build log panel in Visual Studio when the Rebuild Solution action has completed. In folder qiqqa-open-source/Qiqqa/bin/Release/ folder there will be Qiqqa.exe and other files if you don't need the installer.

Preparing the release

There are several scripts which help to prepare the release.

• npm run refresh-data is a helper script which edits the Unit Test C# source code to ensure that all test data reference files ('fixtures') have been included in the test set.

  This one comes in handy if, for instance, you add a bunch of BibTeX test files which should be parse-tested or otherwise. This script will find those (when you have placed them in the TestData/... directory tree) and add comments and code lines in the appropriate Unit Test C# source files to ensure the new files show up in the tests.

• npm run syncver will synchronize all Qiqqa parts to have the same version number info.

  The master major version is obtained from the package.json file — Qiqqa has historically used only the major version number to identify a Qiqqa version. Experimental prereleases, etc. can be identified in Qiqqa Open Source by watching the full version number as it is shown during Qiqqa start up and elsewhere in the application.

• npm run bump : this will bump the Qiqqa major version number by +1, i.e. this command should be run after every official release as the next time a newer (higher) Qiqqa version should be reported by the binaries to be built.

• ./update_CHANGELOG.sh : grabs the git log output and dumps that into CHANGELOG_full.md

  You can later postprocess CHANGELOG_full.md file using Beyond Compare to produce a readable CHANGELOG.md file.

• ./superclean.sh : this script cleans up everything that has been written by Visual Studio in the devtree.

  If you run this script and restart Visual Studio afterwards, you must re-configure Visual Studio configuration. See that the active "Solution" is "Release+SETUP" and in dialog from menu Build > Configuration Manager for solutions named "Debug" and "Release" two projects "ClickOnceUninstaller" and "QiqqaPackager" would be unchecked.

• ./build_installer.sh : the alternative to building the Qiqqa.Packager project and the older way to build a Qiqqa setup.exe installer.