Raqm is a small library that encapsulates the logic for complex text layout and provide a convenient API.
It currently provides bidirectional text support (using FriBiDi), shaping (using HarfBuzz), and proper script itemization. As a result, Raqm can support most writing systems covered by Unicode.
The documentation can be accessed on the web at:
Raqm (Arabic: رَقْم) is writing, also number or digit and the Arabic word for digital (رَقَمِيّ) shares the same root, so it is a play on “digital writing”.
Raqm depends on the following libraries:
To build the documentation you will also need:
To install dependencies on Ubuntu:
sudo apt-get install libfreetype6-dev libharfbuzz-dev libfribidi-dev \
libglib2.0-dev gtk-doc-tools
On Mac OS X you can use Homebrew:
brew install freetype harfbuzz fribidi glib gtk-doc
export XML_CATALOG_FILES="/usr/local/etc/xml/catalog" # for the docs
Once you have the source code and the dependencies, you can proceed to build.
The build method maintained here is CMake.
To build the library, type from source tree directory:
mkdir build
cd build
cmake ..
make
To install the library, type with root privileges:
make install
make clean
Main available cmake flags:
DENABLE_GTK_DOCto build the documentation.DUNIT_TESTto build unit tests.DWANT_DEBUGto enable debug mode.STATIC_LIBto build a static library.RAQM_INSTALL_INCLUDE_DIRto specify the install include path.RAQM_INSTALL_LIB_DIRto specify the install lib path.
To build the documentation, pass -DENABLE_GTK_DOC=1 to the cmake command.
cmake -DENABLE_GTK_DOC=1 ..
make
make docs
It will create an "html" directory in TOP_LEVEL/build/raqm/html
To run the units tests, pass -DUNIT_TEST=1 to the cmake command.
cmake -DUNIT_TEST=1 ..
make
ctest
Before compiling, the following development libraries need to be installed.
You can build FreeType natively on windows, just follow the Freetype build instructions. Also you can build HarfBuzz natively on windows by following HarfBuzz build instructions for windows. Make sure that you build HarfBuzz with FreeType option on. You can get the Freetype's headers and library from the first step. For FriBiDi, there is no official way to build it on windows. Fortunately, ShiftMediaProject provides a native Visual Studio project for it. You have to build all pre-build optional components before you build FriBiDi itself.
First get the source code using git:
git clone https://github.com/HOST-Oman/libraqm-cmake.git
To make build process easier, we make assumptions on the directory structure are made to automate the discovery of dependencies. This recommended directory structure is described below:
win/
include /
lib /
If you do not use the recommended structure you will need to enter paths by hand in CmakeLists.txt. Source and build directories can be located anywhere.
After building all prerequisite libraries, copy their headers into include directory and their libraries (*.lib) into lib directory.
Now you can use raqm-dependencies repository to get required libraries, then pass RAQM_DEPENS_DIR
- Set up a work directory as described above.
- Open the CMake gui.
- Set "Where is the source code" to wherever you put the Libraqm sources (from the released tarball or the git repository).
- Set "Where to build the binaries" to a new empty directory (could be anywhere and any name, for example naming it raqm-build, at the same folder location as your unzipped Libraqm source folder was put).
- Press Configure button. The first time that the project is configured, CMake will bring up a window asking you to "Specify the generator for this project" i.e. which compiler you wish to use. Select Visual Studio 14 2015 (or Visual Studio 14 2015 Win64 for 64-bit), and press Finish. CMake will now do a check on your system and will produce a preliminary build configuration.
- CMake adds new configuration variables in red. Some have a value ending with -NOTFOUND. These variables should receive your attention. Some errors will prevent Libraqm from building and others will simply invalidate some options without causing build errors. You can set the right path for each prerequisite libraries.
- Repeat the process from step 5, until Generate button is enabled.
- Press Generate button.
- Start Visual Studio 2015 and open the Libraqm solution (raqm.sln) located in "Where to build the binaries".
- Choose the "Release" build in the toolbar. The right menu should read Win32 for 32-bits or x64 for 64-bits.
- Generate the solution with F7 key or right-click the top level "Solution raqm" in the Solution Explorer and choose Build.
- If there are build errors, return to CMake, clear remaining errors, Configure button and Generate button .
- When Visual Studio is able to build everything without errors, right-click on the INSTALL project (further down within the "Solution raqm" solution) and choose Build, which will put the include and lib files in ${CMAKE_INSTALL_PREFIX}
- Enjoy!
If you want to use the command line (cmd or powershell) to build libraqm, follow the bleow steps: 1- set up the directory structure as above 2- navigate to the libraqm source code directory. 3- create a new directory for building in side source code directory , and name it build
mkdir build
4- then
cd build
5- then run cmake command to make building instructions:
cmake ..
if you want to enable debug mode, unit testing & static build use:
cmake -DUNIT_TEST=1 -DWANT_DEBUG=1 -DSTATIC_LIB=1 ..
if you want to specify required libraries directory, pass RAQM_DEPENS_DIR
cmake -DRAQM_DEPENS_DIR:PATH="the path to raqm-dependencies build folder" ..
6- the run build command:
# build the library for Release and Debug
cmake --build . --config Debug
7- if you enable unit tests option, you can run tests:
ctest -C "Debug"
Once you have made a change that you are happy with, contribute it back, we’ll be happy to integrate it! Just fork the repository and make a pull request.
The following projects have patches to support complex text layout using Raqm: