Stratus3D

A blog on software engineering by Trevor Brown

Building ZealDocs for OSX

ZealDocs is an open source Qt app that provides offline documentation browsing. It’s cross-platform but not supported on OSX. I’ve been using ZealDocs for a while now on my Ubuntu machine and wanted to use on OSX too. I figured it was possible to get it compiled on OSX, so after some trial and error I finally figured it out. I was using OSX 10.10 when I came up with these steps, so tweaks to this process may be necessary if you are running the latest version of OSX.

Dependencies

First you will need to install all the ZealDocs dependencies. If your using Homebrew it’s easy:

brew install qt5 qt5-qtwebengine qt5-sqlite-plugin libarchive

If you’re not using Homebrew you will need to either find the equivalent packages in your own package manager or install these packages by hand.

Download ZealDocs

cd to the directory you want to build ZealDocs in (you can move it to /Applications after it’s compiled) and clone it down and enter the project directory:

git clone https://github.com/zealdocs/zeal.git
cd zeal

Configure

You will need to add the include and lib paths for the sqlite and libarchive libraries to the src/libs/core/core.pri file. You can find the versions of each package you have installed by running brew info <package name>. The command I ran looked like this:

cat << EOF >> src/libs/core/core.pri
macx: {
    INCLUDEPATH += /usr/local/Cellar/libarchive/3.2.2/include
    LIBS += -L/usr/local/Cellar/libarchive/3.2.2/lib -larchive
    INCLUDEPATH += /usr/local/Cellar/sqlite/3.15.2/include
    LIBS += -L/usr/local/Cellar/sqlite/3.15.2/lib -lsqlite3

}
EOF

Of course your sqlite and libarchive versions may be different. Note that this is a critical step, if any of these paths are wrong the build will fail.

Build

Now that we have everything configured we can build ZealDocs:

/usr/local/opt/qt5/bin/qmake -makefile
make

If all goes well you should see a Zeal.app/ directory inside of the projects bin/ directory.

Install

Copy the Zeal.app directory into your /Applications directory to install it.

cp bin/Zeal.app /Applications

Once you have it in your /Applications directory you will have to tell OSX to run the app even though it can’t identify the developer. Once you have done this you should be able to open the app and begin using it.

Finally, ZealDocs can be started from the command line with a search term. You could add the appropriate path to your $PATH, but I’ve found an alias to be a little easier. Add this to your .bashrc if you want to make zeal available as an alias in your shell:

alias zeal='/Applications/Zeal.app/Contents/MacOS/Zeal'

When you start a new shell session you should be able to use zeal:

zeal erlang:ping

Conclusion

I’ve been pretty happy we ZealDocs so far, and it’s nice I can now run it on OSX as well as all my other linux distros. Since Zeal is cross platform it doesn’t really integrate with anything OSX-specific so your looking for something a little nicer you should check out Dash. Dash is a proprietary app that has some extra features that make it a little easier to use on OSX.

Update 12/15/2016 - Automation

After writing this post I realized it would be nice to have a Bash script do all this. I wrote one and checked it into my dotfiles repository.

References

  • https://github.com/zealdocs/zeal/wiki/Build-Instructions-for-OS-X
  • http://mazhuang.org/2016/01/16/build-zeal-for-mac-osx/
  • https://github.com/zealdocs/zeal/pull/372
  • http://www.howtogeek.com/205393/gatekeeper-101-why-your-mac-only-allows-apple-approved-software-by-default/
  • https://kapeli.com/dash
  • https://github.com/Stratus3D/dotfiles/blob/master/scripts/setup/install/zeal.sh