1# Rime with Mac 2 3## Preparation 4 5Install Xcode with command line tools. 6 7Install other build tools: 8 9``` sh 10brew install cmake git 11``` 12 13## Get the code 14 15``` sh 16git clone --recursive https://github.com/rime/librime.git 17``` 18or [download from GitHub](https://github.com/rime/librime), then get code for 19third party dependencies separately. 20 21## Install Boost C++ libraries 22 23Boost is a third-party library which librime code heavily depend on. 24These dependencies include a few compiled (non-header-only) Boost libraries. 25 26**Option 1 (recommended):** Download and build Boost from source. 27 28``` sh 29cd librime 30make xcode/thirdparty/boost 31``` 32 33The make script will download Boost source tarball, extract it to 34`librime/thirdparty/src/boost_<version>` and create needed static libraries 35for building macOS uinversal binary. 36 37Set shell variable `BOOST_ROOT` to the path to `boost_<version>` directory prior 38to building librime. 39 40``` sh 41export BOOST_ROOT="$(pwd)/thirdparty/src/boost_1_75_0" 42``` 43 44**Option 2:** Install Boost libraries from Homebrew. 45 46``` sh 47brew install boost 48``` 49 50This is a time-saving option if you are building and installing Rime only for your 51own Mac computer. 52 53Built with Homebrewed version of Boost, the `librime` binary will not be 54portable to machines without certain Homebrew formulae installed. 55 56**Option 3:** Install an older version of Boost libraries from Homebrew. 57 58Starting from version 1.68, `boost::locale` library from Homebrew depends on 59`icu4c`, which is not provided by macOS. 60 61Make target `xcode/release-with-icu` tells cmake to link to ICU libraries 62installed locally with Homebrew. This is only required if building with the 63[`librime-charcode`](https://github.com/rime/librime-charcode) plugin. 64 65To make a portable build with this plugin, install an earlier version of 66`boost` that wasn't dependent on `icu4c`: 67 68``` sh 69brew install boost@1.60 70brew link --force boost@1.60 71``` 72 73## Build third-party libraries 74 75Required third-party libraries other than Boost are included as git submodules: 76 77``` sh 78# cd librime 79 80# if you haven't checked out the submodules with git clone --recursive ..., do: 81# git submodule update --init 82 83make xcode/thirdparty 84``` 85 86This builds libraries located at `thirdparty/src/*`, and installs the build 87artifacts to `thirdparty/include`, `thirdparty/lib` and `thirdparty/bin`. 88 89You can also build an individual library, eg. `opencc`, with: 90 91``` sh 92make xcode/thirdparty/opencc 93``` 94 95## Build librime 96 97``` sh 98make xcode 99``` 100This creates `build/lib/Release/librime*.dylib` and command line tools 101`build/bin/Release/rime_*`. 102 103Or, create a debug build: 104 105``` sh 106make xcode/debug 107``` 108 109## Run unit tests 110 111``` sh 112make xcode/test 113``` 114 115Or, test the debug build: 116 117``` sh 118make xcode/test-debug 119``` 120 121## Try it in the console 122 123``` sh 124( 125 cd debug/bin; 126 echo "congmingdeRime{space}shurufa" | Debug/rime_api_console 127) 128``` 129 130Use it as REPL, quit with <kbd>Control+d</kbd>: 131 132``` sh 133(cd debug/bin; ./Debug/rime_api_console) 134``` 135