# Rime with Mac

## Preparation

Install Xcode with command line tools.

Install other build tools:

``` sh
brew install cmake git
```

## Get the code

``` sh
git clone --recursive https://github.com/rime/librime.git
```
or [download from GitHub](https://github.com/rime/librime), then get code for
third party dependencies separately.

## Install Boost C++ libraries

Boost is a third-party library which librime code heavily depend on.
These dependencies include a few compiled (non-header-only) Boost libraries.

**Option 1 (recommended):** Download and build Boost from source.

``` sh
cd librime
make xcode/thirdparty/boost
```

The make script will download Boost source tarball, extract it to
`librime/thirdparty/src/boost_<version>` and create needed static libraries
for building macOS uinversal binary.

Set shell variable `BOOST_ROOT` to the path to `boost_<version>` directory prior
to building librime.

``` sh
export BOOST_ROOT="$(pwd)/thirdparty/src/boost_1_75_0"
```

**Option 2:** Install Boost libraries from Homebrew.

``` sh
brew install boost
```

This is a time-saving option if you are building and installing Rime only for your
own Mac computer.

Built with Homebrewed version of Boost, the `librime` binary will not be
portable to machines without certain Homebrew formulae installed.

**Option 3:** Install an older version of Boost libraries from Homebrew.

Starting from version 1.68, `boost::locale` library from Homebrew depends on
`icu4c`, which is not provided by macOS.

Make target `xcode/release-with-icu` tells cmake to link to ICU libraries
installed locally with Homebrew. This is only required if building with the
[`librime-charcode`](https://github.com/rime/librime-charcode) plugin.

To make a portable build with this plugin, install an earlier version of
`boost` that wasn't dependent on `icu4c`:

``` sh
brew install boost@1.60
brew link --force boost@1.60
```

## Build third-party libraries

Required third-party libraries other than Boost are included as git submodules:

``` sh
# cd librime

# if you haven't checked out the submodules with git clone --recursive ..., do:
# git submodule update --init

make xcode/thirdparty
```

This builds libraries located at `thirdparty/src/*`, and installs the build
artifacts to `thirdparty/include`, `thirdparty/lib` and `thirdparty/bin`.

You can also build an individual library, eg. `opencc`, with:

``` sh
make xcode/thirdparty/opencc
```

## Build librime

``` sh
make xcode
```
This creates `build/lib/Release/librime*.dylib` and command line tools
`build/bin/Release/rime_*`.

Or, create a debug build:

``` sh
make xcode/debug
```

## Run unit tests

``` sh
make xcode/test
```

Or, test the debug build:

``` sh
make xcode/test-debug
```

## Try it in the console

``` sh
(
  cd debug/bin;
  echo "congmingdeRime{space}shurufa" | Debug/rime_api_console
)
```

Use it as REPL, quit with <kbd>Control+d</kbd>:

``` sh
(cd debug/bin; ./Debug/rime_api_console)
```

# Rime with Windows

## Prerequisites

`librime` is tested to work on Windows with the following combinations of build
tools and libraries:

  - Visual Studio 2017
  - [Boost](http://www.boost.org/)=1.64
  - [cmake](http://www.cmake.org/)>=3.8

and

  - Visual Studio 2015
  - [Boost](http://www.boost.org/)=1.60
  - [cmake](http://www.cmake.org/)>=3.8

Boost and cmake versions need to match higher VS version.

[Python](https://python.org)>=2.7 is needed to build opencc dictionaries.

## Get the code

``` batch
git clone --recursive https://github.com/rime/librime.git
```
or [download from GitHub](https://github.com/rime/librime).

## Setup a build environment

Copy `env.bat.template` to `env.bat` and edit the file according to your setup.
Specifically, make sure `BOOST_ROOT` is set to the root directory of Boost
source tree; modify `BJAM_TOOLSET`, `CMAKE_GENERATOR` and `PLATFORM_TOOLSET` if
using a different version of Visual Studio; also set `DEVTOOLS_PATH` for build
tools installed to custom location.

When prepared, do the following in a *Developer Command Prompt* window.

## Build Boost

``` batch
build.bat boost
```

## Build third-party libraries

``` batch
build.bat thirdparty
```
This builds dependent libraries in `thirdparty\src\*`, and copies artifacts to
`thirdparty\lib` and `thirdparty\bin`.

## Build librime

``` batch
build.bat librime
```
This creates `build\lib\Release\rime.dll`.

Build artifacts - the shared library along with API headers and supporting files
are gathered in `dist` directory.

## Try it in the console

`librime` comes with a REPL application which can be used to test if the library
is working.

``` batch
copy /Y build\lib\Release\rime.dll build\bin
cd build\bin
echo congmingdeRime{space}shurufa | Release\rime_api_console.exe > output.txt
```

Instead of redirecting output to a file, you can set appropriate code page
(`chcp 65001`) and font in the console to work with the REPL interactively.

<meta charset="UTF-8">

RIME: Rime Input Method Engine
===
[![Build Status](https://travis-ci.org/rime/librime.svg)](https://travis-ci.org/rime/librime)
[![Build status](https://ci.appveyor.com/api/projects/status/github/rime/librime?svg=true)](https://ci.appveyor.com/project/rime/librime)
[![GitHub release](https://img.shields.io/github/release/rime/librime.svg)](https://github.com/rime/librime/releases)
[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)

Rime with your keystrokes.

Project home
---
[rime.im](https://rime.im)

License
---
[The 3-Clause BSD License](https://opensource.org/licenses/BSD-3-Clause)

Features
===
  - A modular, extensible input method engine in cross-platform C++ code,
    built on top of open-source technologies
  - Covering features found in a large variety of Chinese input methods,
    either shape-based or phonetic-based
  - Built with native support for Traditional Chinese, conversion to Simplified
    Chinese and other regional standards via OpenCC
  - Rime input schema, a DSL in YAML syntax for fast trying out innovative ideas
    of input method design
  - Spelling Algebra, a mechanism to create variant spelling, especially useful
    for Chinese dialects
  - Support for chord-typing with a generic Qwerty keyboard

Install
===
Follow the instructions to build librime on platforms other than Linux:
  - [macOS](https://github.com/rime/librime/tree/master/README-mac.md)
  - [Windows](https://github.com/rime/librime/tree/master/README-windows.md)

Build dependencies
---
  - compiler with C++14 support
  - capnproto>=0.7.0
  - cmake>=2.8
  - libboost>=1.48
  - libcapnp>=0.7.0
  - libglog (optional)
  - libleveldb
  - libmarisa
  - libopencc>=1.0.2
  - libyaml-cpp>=0.5
  - libgtest (optional)

Runtime dependencies
---
  - libboost
  - libcapnp
  - libglog (optional)
  - libleveldb
  - libmarisa
  - libopencc
  - libyaml-cpp

Build and install librime on Linux
---
```
make
sudo make install
```

Frontends
===

Official:
  - [ibus-rime](https://github.com/rime/ibus-rime): IBus frontend for Linux
  - [Squirrel](https://github.com/rime/squirrel): frontend for macOS
  - [Weasel](https://github.com/rime/weasel): frontend for Windows

Third-party:
  - [emacs-rime](https://github.com/DogLooksGood/emacs-rime): frontend for Emacs
  - [fcitx-rime](https://github.com/fcitx/fcitx-rime): Fcitx frontend for Linux
  - [iRime](https://github.com/jimmy54/iRime): frontend for iOS
  - [PIME](https://github.com/EasyIME/PIME): frontend for Windows
  - [Trime](https://github.com/osfans/trime): frontend for Android
  - [XIME](https://github.com/stackia/XIME): frontend for macOS

Plugins
===
  - [librime-charcode](https://github.com/rime/librime-charcode) Module that
    deals with character encoding; depends on boost::locale and ICU libraries
  - [librime-legacy](https://github.com/rime/librime-legacy) Legacy module with
    GPL-licensed code

Related works
===
  - [plum](https://github.com/rime/plum): Rime configuration manager and input
    schema repository
  - [Combo Pinyin](https://github.com/rime/home/wiki/ComboPinyin): an innovative
    chord-typing practice to input Pinyin
  - essay: the vocabulary and language model for Rime
  - [SCU](https://github.com/neolee/SCU): Squirrel Configuration Utilities

Credits
===
We are grateful to the makers of the following open source libraries:

  - [Boost C++ Libraries](http://www.boost.org/) (Boost Software License)
  - [google-glog](https://github.com/google/glog) (The 3-Clause BSD License)
  - [Google Test](https://github.com/google/googletest) (The 3-Clause BSD License)
  - [LevelDB](https://github.com/google/leveldb) (The 3-Clause BSD License)
  - [marisa-trie](https://github.com/s-yata/marisa-trie) (BSD 2-Clause License, LGPL 2.1)
  - [OpenCC](https://github.com/BYVoid/OpenCC) (Apache License 2.0)
  - [yaml-cpp](https://github.com/jbeder/yaml-cpp) (MIT License)

Contributors
===
  - [佛振](https://github.com/lotem)
  - [鄒旭](https://github.com/zouxu09)
  - [Weng Xuetian](http://csslayer.info)
  - [Chongyu Zhu](http://lembacon.com)
  - [Zhiwei Liu](https://github.com/liuzhiwei)
  - [BYVoid](http://www.byvoid.com)
  - [雪齋](https://github.com/LEOYoon-Tsaw)
  - [瑾昀](https://github.com/kunki)
  - [osfans](https://github.com/osfans)
  - [jakwings](https://github.com/jakwings)
  - [Prcuvu](https://github.com/Prcuvu)
  - [hchunhui](https://github.com/hchunhui)