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