Installation

Install:

• macOS
• Windows
• Ubuntu
• Debian
• Fedora
• FreeBSD
• Arch Linux
• NixOS
• openSUSE
• WSL

Build:

• build on macOS
• build on Windows
• build on Ubuntu
• build on Debian
• build on Fedora
• build on Gentoo
• build on NixOS
• build on WSL

Docker:

• build and run container

Tarball:

• download tarball

Unfortunately links above must have trailing '-' to workaround GitHub MD to HTML rendering bug. Therefore these links are broken in Markdown editors (including MF).

Install a package

Install MindForger using a package.

macOS

Install MindForger on macOS either using brew or by downloading .dmg.

Homebrew

Install MindForger using HomeBrew:

brew install mindforger

Disk iMaGe

Install MindForger using .dmg:

• download .dmg from GitHub releases

Install .dmg:

• Open/mount .dmg
• Drag and drop/copy mindforger from .dmg to Applications
• Run MindForger

MindForger creates copy of the documentation in your home directory (~/mindforger-repository) and opens it as default repository.

Windows

Install MindForger using installer.

• Download installer executable from https://github.com/dvorka/mindforger/releases (or try nightly build)
• Run installer.

WSL

Install Windows Subsystem for Linux (WSL) and check that you have Ubuntu 16.04 or newer:

lsb_release -a
  ...
  Release:        16.04
  Codename:       xenial

If not, then run sudo do-release-upgrade.

Install and start an X server for Windows like Xming.

---

Install MindForger from PPA. Add my PPA to Apt, trust GPG key, install MindForger and run it:

# add PPA to trusted repositories
sudo add-apt-repository ppa:ultradvorka/productivity

# update sources
sudo apt update

# install MindForger
sudo apt install mindforger

# run MindForger
DISPLAY=:0.0 mindforger

Ubuntu

Install MindForger from PPA. Add my Lauchpad hosted PPA and install MindForger:

# add PPA to trusted repositories
sudo add-apt-repository ppa:ultradvorka/productivity

# update sources
sudo apt update

# install MindForger
sudo apt install mindforger

Debian

Install MindForger on Debian from PPA. Add my PPA, trust GPG key and install MindForger:

# add PPA to APT sources:
sudo bash -c 'echo -e "\ndeb https://www.mindforger.com/debian stretch main" > /etc/apt/sources.list.d/mindforger.list'

# import PPA's GPG key
wget -qO - http://www.mindforger.com/gpgpubkey.txt | sudo apt-key add -

# update sources
sudo apt update

# install MindForger
sudo apt install mindforger

See also http://www.mindforger.com/debian/

Fedora

Install MindForger on Fedora:

• download RPM from GitHub releases

Install RPM:

sudo dnf install mindforger-MAJOR.MINOR.REVISION.rpm

FreeBSD

Install MindForger on FreeBSD:

pkg install deskutils/mindforger
pkg install mindforger

(port commit)

Arch Linux

Install MindForger from Arch User Repository (AUR):

• https://aur.archlinux.org/packages/mindforger/

NixOS

Install MindForger package on NixOS:

nix-env -i mindforger

openSUSE

Install MindForger on openSUSE:

sudo zypper in opi
opi mindforger

Build from source code

Build MindForger from source code.

Build on macOS

Build MindForger on macOS Sierra 10.12+.

Open Terminal and install/update Xcode command line tools:

xcode-select --install

Install/update HomeBrew package manager:

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew doctor

Install build tools and dependencies:

brew install ccache

Download Qt from https://www.qt.io/download and in its online installer choose:

• Qt/Qt 5.x.x
  • latest available 5.x.x (Qt 5.9.9 or any newer Qt relese)
  • you can skip components like Android or iOS
• Developer and Designer Tools
  • Qt Creator
  • qmake
  • CMake
  • Qt Installer Framework

Once Qt is installed you can use ~/Qt/MaintennanceTool.app to add/remove Qt components.

Get source code:

git clone https://github.com/dvorka/mindforger.git
git submodule init
git submodule update

There are two ways how to build MindForger Disk iMaGe package:

1. either using scripts from MindForger's GitHub repository:
   • build/macos/mindforger-build.sh which creates MindForger executable
   • build/macos/dmg-package-build.sh which creates Disk iMaGe .dmg package on top of binary executable build made by mindforger-build.sh
2. or using the steps described below

Add dependencies to PATH:

• fix paths: username, Qt and its components versions might be different
• add PATH modifications below to your .bash_profile and/or .bashrc or .zshrc depending on your shell (configuration)
• don't forget to apply changes e.g. using . .bashr_profile

# clang
export PATH="/Users/username/Qt/5.x.x/clang_64/bin:${PATH}"
# cmake
export PATH="${PATH}:/Users/username/Qt/Tools/CMake/CMake.app/Contents/bin"
# installer
export PATH="${PATH}:/Users/username/Qt/Tools/QtInstallerFramework/3.2/bin"

Get source code:

git clone https://github.com/dvorka/mindforger.git
git submodule init
git submodule update

Build dependencies:

# build dependency: cmark-gfm
cd mindforger/deps/cmark-gfm
mkdir build && cd build
cmake -DCMARK_TESTS=OFF -DCMARK_SHARED=OFF ..
cmake --build .

Compile sources from repository root directory:

qmake -r mindforger.pro
# consider adding -j parameter with the number of CPU cores to use e.g. make -j 8
make

Optionally install MindForger:

cd app && cp -rvf mindforger.app /Applications

Install documentation and stencils:

# clone MindForger documentation repository to home directory - location and directory name matters
cd ~
git clone https://github.com/dvorka/mindforger-repository.git

Run MindForger either as application or using command line:

/Applications/mindforger.app/contents/MacOS/mindforger

---

Qt Creator development environment setup:

• start Qt Creator as application
• open project mindforger.pro
• configure project: clang kit, debug and release profiles
• menu Build/Run qmake
• menu Build/Build all
• menu Build/Run

Build .dmg distribution:

• start terminal session
• change to mindforger/build/macos
• run build/macos/dmg-package-build.sh
• check .dmg distro created in mindforger/app/mindforger.dmg

Build on Windows

Build MindForger on Microsoft Windows.

Install build tools:

• Install Microsoft Visual Studio IDE Community edition.
  • Choose Desktop development with C++ in installer.
• Install Qt and Qt Creator IDE
  • Qt version - choose latest 5.x.x Qt release available (must be Qt 5.9.5 or newer, suggested Qt 5.12.0 or newer)
  • Choose Qt > Qt 5.x.x > QMSVC 2017 64-bit
  • Choose Qt > Qt 5.x.x > Qt WebEngine
  • Choose Qt > Developer and Designer tools > Qt Creator
• Install cmake
• Install patch

Get source code from GitHub:

• Create directory where you want to build MindForger e.g. C:\Users\USER\mindforger-build

# create and change to build directory
C: | cd %HOMEPATH% | mkdir mindforger-build | cd mindforger-build
# clone MindForger repository
git clone https://github.com/dvorka/mindforger.git
# update repository sub-modules
cd mindforger
git submodule init
git submodule update

• MindForger sources can be found in C:\Users\USER\mindforger-build\mindforger

Build dependencies:

• build cmark-gfm:

cd deps\cmark-gfm
mkdir build                                                                                                                                                                                                      
cd build                                                                                                                                                                                                         
cmake -G "Visual Studio 15 2017 Win64" -DCMAKE_CONFIGURATION_TYPES=Debug;Release -DCMARK_TESTS=OFF -DCMARK_SHARED=OFF ..
cmake --build . --config Release -- /m

Get default MindForger repository - documentation and examples (will be loaded on the first start):

# change to home directory
C: | cd %HOMEPATH%
# clone MindForger documentation
git clone https://github.com/dvorka/mindforger-repository.git

Build MindForger in Qt Creator:

1. Start Qt Creator
2. Open MindForger project:
   • Welcome/Open project
   • Choose C:\Users\USER\mindforger-build\mindforger\mindforger.pro as project file.
3. Choose kit:
   • Desktop Qt 5.x.x MSVC2017 64bit
4. Set build directory:
   • Set left toolbar's Projects/Build Settings/Build directory to C:\Users\USER\mindforger-build\mindforger
5. Set build configuration:
   • Set Projects/Build Settings/Edit build configuration choose Release
6. Build:
   • Menu Build/Build All

Run MindForger from Qt Creator:

• Menu Build\Run

Create installer:

• Install JRSoftware Inno Setup 5
• Prepare development environment. Change path according to your Qt installation
  • Run %QT_HOME%\5.x.x\msvc2017_64\bin\qtenv2.bat
• Gather dependencies
  • cd C:\Users\USER\mindforger-build\mindforger
  • %QT_HOME%\5.x.x\msvc2017_64\bin\windeployqt app\release\mindforger.exe --dir app\release\bin --no-compiler-runtime
• Build installer - update path to vcredist_x64.exe in the command below according to your setup:
  • cd C:\Users\USER\mindforger-build\mindforger
  • "C:\Program Files (x86)\Inno Setup 5\ISCC.exe" /Qp /DVcRedistPath="c:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Redist\MSVC\14.16.27012\vcredist_x64.exe" build\windows\installer\mindforger-setup.iss
• MindForger installer can be found in app\release\installer folder.

To create debug version of MindForger and executable replace debug with release in the steps above and use mindforger-setup-debug.iss installer configuration.

Build on WSL

Build MindForger on Windows Subsystem for Linux (WSL).

Install build tools:

sudo apt-get install build-essential zlib1g-dev libhunspell-dev libqt5webkit5-dev qttools5-dev-tools qt5-default ccache

Update gcc and g++ to version 5 (at least):

# adds the the test toolchain which includes gcc-5 and g++5 
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt-get update
sudo apt-get install gcc-5 g++-5
# substitute gcc-5 for gcc and g++-5 for g++ (current version)
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-5 60 --slave /usr/bin/g++ g++ /usr/bin/g++-5

Get source code:

# clone MindForger repository
git clone https://github.com/dvorka/mindforger.git
# update repository sub-modules
cd mindforger
git submodule init
git submodule update

Build dependencies:

# build cmark-gfm
cd mindforger/deps/cmark-gfm
mkdir build && cd build
cmake -DCMARK_TESTS=OFF -DCMARK_SHARED=OFF ..
cmake --build .

Compile and install from Git repository root directory:

qmake -r mindforger.pro
# consider speeding up compilation by increasing the number of CPU cores to use e.g. make -j8
make
sudo make install

Install documentation and stencils:

# clone MindForger documentation repository to home directory (location and directory name matters)
cd ~
git clone https://github.com/dvorka/mindforger-repository.git

# verify MindForger repository installation
ls mindforger-repository
  limbo  memory  mind  stencils

Run MindForger and start your XServer for Windows (e.g. Xming)

DISPLAY=:0.0 ./mindforger

Build on Ubuntu

Build MindForger on Ubuntu 16.04 or later.

Install package dependencies:

sudo apt-get install build-essential zlib1g-dev libhunspell-dev libqt5webkit5-dev qttools5-dev-tools qt5-default ccache

Get source code:

# clone MindForger repository
git clone https://github.com/dvorka/mindforger.git
# update repository sub-modules
cd mindforger
git submodule init
git submodule update

Build dependencies:

# build cmark-gfm
cd mindforger/deps/cmark-gfm
mkdir build && cd build
cmake -DCMARK_TESTS=OFF -DCMARK_SHARED=OFF ..
cmake --build .

Compile sources and install MindForger from Git repository root directory:

qmake -r mindforger.pro
# consider speeding up compilation by increasing the number of CPU cores to use e.g. make -j8
make
sudo make install

Install documentation and stencils:

# clone MindForger documentation repository to home directory (location and directory name matters)
cd ~
git clone https://github.com/dvorka/mindforger-repository.git

Run MindForger:

./mindforger

See also mindforger/build/ubuntu/build-all-clean-system.sh

Build on Debian

Build MindForger on Debian Stretch or later.

Install package dependencies:

sudo apt-get install build-essential zlib1g-dev libhunspell-dev libqt5webkit5-dev qttools5-dev-tools qt5-default ccache

Get source code:

# clone MindForger repository
git clone https://github.com/dvorka/mindforger.git
# update repository sub-modules
git submodule init
git submodule update

Build dependencies:

# build cmark-gfm
cd mindforger/deps/cmark-gfm
mkdir build && cd build
cmake -DCMARK_TESTS=OFF -DCMARK_SHARED=OFF ..
cmake --build .

Compile and install from Git repository root directory:

qmake -r mindforger.pro
# consider speeding up compilation by increasing the number of CPU cores to use e.g. make -j8
make
sudo make install

Install documentation and stencils:

# clone MindForger documentation repository to home directory (location and directory name matters)
cd ~
git clone https://github.com/dvorka/mindforger-repository.git

Run MindForger:

./mindforger

Build on Fedora

Build MindForger on Fedora.

Install package dependencies:

sudo dnf install zlib-devel hunspell-devel qt-devel qt5-devel ccache

Get source code:

# clone MindForger repository
git clone https://github.com/dvorka/mindforger.git
# update repository sub-modules                                            
git submodule init
git submodule update

Build dependencies:

# build cmark-gfm
cd mindforger/deps/cmark-gfm
mkdir build && cd build
cmake -DCMARK_TESTS=OFF -DCMARK_SHARED=OFF ..
cmake --build .

Compile and install from Git repository root directory:

qmake-qt5 -r mindforger.pro
# consider speeding up compilation by increasing the number of CPU cores to use e.g. make -j8
make
sudo make install

Install documentation and stencils:

# clone MindForger documentation repository to home directory (location and directory name matters)
cd ~
git clone https://github.com/dvorka/mindforger-repository.git

Run MindForger:

./mindforger

Build on Gentoo

Build MindForger on Gentoo:

Install package dependencies.

Get source code:

# clone MindForger repository
git clone https://github.com/dvorka/mindforger.git
# update repository sub-modules                                            
git submodule init
git submodule update

Build dependencies:

# build cmark-gfm
cd mindforger/deps/cmark-gfm
mkdir build && cd build
cmake -DCMARK_TESTS=OFF -DCMARK_SHARED=OFF ..
cmake --build .

Compile and install from Git repository root directory:

qmake CONFIG+=mfwebengine -r mindforger.pro
# consider speeding up compilation by increasing the number of CPU cores to use e.g. make -j8
make
sudo make install

Install documentation and stencils:

# clone MindForger documentation repository to home directory (location and directory name matters)
cd ~
git clone https://github.com/dvorka/mindforger-repository.git

Run MindForger:

./mindforger

Build on NixOS

Build MindForger on Gentoo:

Install package dependencies.

Get source code:

# clone MindForger repository
git clone https://github.com/dvorka/mindforger.git
# update repository sub-modules                                            
git submodule init
git submodule update

Build dependencies:

# build cmark-gfm
cd mindforger/deps/cmark-gfm
mkdir build && cd build
cmake -DCMARK_TESTS=OFF -DCMARK_SHARED=OFF ..
cmake --build .

Compile and install from Git repository root directory:

qmake CONFIG+=mfwebengine -r mindforger.pro
# consider speeding up compilation by increasing the number of CPU cores to use e.g. make -j8
make
sudo make install

Install documentation and stencils:

# clone MindForger documentation repository to home directory (location and directory name matters)
cd ~
git clone https://github.com/dvorka/mindforger-repository.git

Run MindForger:

./mindforger

Docker

Run MindForger in Docker container.

Build and run in container

Build Docker image and run MindForger in Docker container.

Build image:

mkdir mindforger

# download Dockerfile
curl https://raw.githubusercontent.com/dvorka/mindforger/master/build/docker/mindforger/Dockerfile > mindforger/Dockerfile

# build image
docker build -t mindforger:latest mindforger

Run container:

# allow access to X server (UNSECURE, but simple):
xhost +local:root

# run image
docker run -it --env="DISPLAY" --env="QT_X11_NO_MITSHM=1" \
    --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" mindforger:latest mindforger

# determine and remember container ID
docker ps -l -q > ~/.mindforger.docker

Run MindForger by starting container:

# start (stopped) container
docker start $(cat ~/.mindforger.docker)

Check also https://github.com/dvorka/mindforger/tree/master/build/docker for handy scripts.

Spell check

MindForger's spell check implementation is based on Hunspell.

Spell check configuration on Linux

Install Hunspell:

sudo apt install hunspell

Download vocabulary for your language from:

• https://extensions.openoffice.org/en/project/english-dictionaries-apache-openoffice

Install vocabulary:

• extract .oxt archive downloaded from the URL above to get .dict and .aff files
• determine Hunspell's vocabulary search path by running:

hunspell -D

• copy downloaded (.dict and .aff) vocabulary files to one of the directories on Hunspell's search path e.g. /usr/share/hunspell

Spell check configuration on Windows

Hunspell is included in MindForger executable, therefore it does not have to be installed.

Download vocabulary for your language from:

• https://extensions.openoffice.org/en/project/english-dictionaries-apache-openoffice

Install vocabulary:

• extract .oxt archive downloaded from the URL above to get .dict and .aff files
• copy downloaded (.dict and .aff) vocabulary files to one of the directories on Hunspell's search path:

C:\Users\<profile>\dictionaries
C:\Users\<profile>\Local Settings\dictionaries
C:\Users\<profile>\AppData\Local\dictionaries