# 从源码编译

## 在 docker 容器内编译和使用

此节介绍在官方编译镜像 [hybridsql](https://hub.docker.com/r/4pdosc/hybridsql) 中编译 OpenMLDB，主要可以用于在容器内试用和开发目的。镜像内置了编译所需要的工具和依赖，因此不需要额外的步骤单独配置它们。关于基于非 docker 的编译使用方式，请参照下面的 [从源码全量编译](#从源码全量编译) 章节。

对于编译镜像的版本，需要注意拉取的镜像版本和 [OpenMLDB 发布版本](https://github.com/4paradigm/OpenMLDB/releases)保持一致。以下例子演示了在 `hybridsql:0.9.0` 镜像版本上编译 [OpenMLDB v0.9.0](https://github.com/4paradigm/OpenMLDB/releases/tag/v0.9.0) 的代码，如果要编译最新 `main` 分支的代码，则需要拉取 `hybridsql:latest` 版本镜像。

1. 下载 docker 镜像
    ```bash
    docker pull 4pdosc/hybridsql:0.9
    ```

2. 启动 docker 容器
    ```bash
    docker run -it 4pdosc/hybridsql:0.9 bash
    ```

3. 在 docker 容器内, 克隆 OpenMLDB, 并切换分支到 v0.9.0
    ```bash
    cd ~
    git clone -b v0.9.0 https://github.com/4paradigm/OpenMLDB.git
    ```

4. 在 docker 容器内编译 OpenMLDB
    ```bash
    cd OpenMLDB
    make
    ```

5. 安装 OpenMLDB, 默认安装到`${PROJECT_ROOT}/openmldb`
    ```bash
    make install
    ```
    至此， 你已经完成了在 docker 容器内的编译工作，你现在可以在容器内开始使用 OpenMLDB 了。

## 从源码全量编译

本章介绍脱离预制容器环境的源码编译方式。

### 硬件要求

- **内存**: 推荐 8GB+.
- **硬盘**: 全量编译需要至少 25GB 的空闲磁盘空间
- **操作系统**: CentOS 7, Ubuntu 20.04 或者 macOS >= 10.15 (Intel Chip), 其他系统未经测试，欢迎提 issue 或 PR
- **CPU 架构**: 目前仅支持 x86 架构，暂不支持例如 ARM 等架构 (注意在 Mac with Apple Silicon 上异构运行 x86 镜像同样暂不支持)

💡 注意：默认关闭了并发编译，其典型的编译时间大约在一小时左右。如果你认为编译机器的资源足够，可以通过调整编译参数 `NPROC` 来启用并发编译功能。这会减少编译所需要的时间但也需要更多但内存。例如下面命令将并发编译数设置成使用四个核进行并发编译：
```bash
make NPROC=4
```

### 依赖工具

- gcc >= 8 或者 AppleClang >= 12.0.0
- cmake 3.20 或更新版本（建议 < cmake 3.24）
- JDK 8
- Python3, Python setuptools, Python wheel
- 如果需要从源码编译 thirdparty, 查看 [third-party's requirement](https://github.com/4paradigm/OpenMLDB/tree/main/third-party) 里的额外要求

### 编译和安装 OpenMLDB

成功编译 OpenMLDB 要求依赖的第三方库预先安装在系统中。因此添加了一个 `Makefile`, 将第三方依赖自动安装和随后执行 CMake 编译浓缩到一行 `make` 命令中。`make` 提供了两种编译方式，对第三方依赖进行不同的管理方式：

- **方式一：自动下载预编译库(仅对特定操作系统版本)：** 编译安装命令为：`make && make install`。编译脚本自动从 [hybridsql](https://github.com/4paradigm/hybridsql-asserts/releases) 和 [zetasql](https://github.com/4paradigm/zetasql/releases) 两个仓库下载必须的预编译好的三方库。目前提供 CentOS 7, Ubuntu 20.04 和 macOS >=  12.0 的预编译包。对于其他操作系统，推荐使用方式二的完整编译。
- **方式二：完整源代码编译(对所有支持的操作系统)：** 如果操作系统不在支持的系统列表中(CentOS 7, Ubuntu 20.04, macOS)，从源码编译是推荐的方式。注意首次编译三方库可能需要更多的时间，在一台 2 核 8 GB 内存机器大约需要一个小时。从源码编译安装第三方库, 传入 `BUILD_BUNDLED=ON`:

   ```bash
   make BUILD_BUNDLED=ON
   make install
   ```

以上 OpenMLDB 安装成功的默认目录放在 `${PROJECT_ROOT}/openmldb`，可以通过修改参数 `CMAKE_INSTALL_PREFIX` 更改安装目录（详见下面章节 [`make` 额外参数](#make-额外参数)）。

### `make` 额外参数

控制 `make` 的行为. 例如，将默认编译模式改成 Debug:

```bash
make CMAKE_BUILD_TYPE=Debug
```

- OPENMLDB_BUILD_DIR: 代码编译路径

  默认: ${PROJECT_ROOT}/build

- CMAKE_BUILD_TYPE

  默认: RelWithDebInfo

- CMAKE_INSTALL_PREFIX: 安装路径

  默认: ${PROJECT_ROOT}/openmldb

- SQL_PYSDK_ENABLE：是否编译 Python SDK

  默认: OFF

- SQL_JAVASDK_ENABLE：是否编译 Java SDK

  默认: OFF

- TESTING_ENABLE：是否编译测试目标

  默认: OFF

- NPROC: 并发编译数

  默认: 1

- CMAKE_EXTRA_FLAGS: 传递给 cmake 的额外参数

  默认: ''

- BUILD_BUNDLED: 从源码编译 thirdparty 依赖，而不是下载预编译包

  默认: OFF

- TCMALLOC_ENABLE: 通过 tcmalloc 的暴露应用的内存信息

  默认: ON

- OPENMLDB_BUILD_TARGET: 只需编译某些target时使用。例如，只想要编译一个测试程序ddl_parser_test，你可以设置`OPENMLDB_BUILD_TARGET=ddl_parser_test`。如果是多个target，用空格隔开。可以减少编译时间，减少编译产出文件，节约存储空间。

  默认: all

- THIRD_PARTY_CMAKE_FLAGS: 编译thirdparty时可以配置额外参数。例如，配置每个thirdparty项目并发编译，`THIRD_PARTY_CMAKE_FLAGS=-DMAKEOPTS=-j8`。thirdparty不受NPROC影响，thirdparty的多项目将会串行执行。
  默认：''

### 并发编译Java SDK

```
make SQL_JAVASDK_ENABLE=ON NPROC=4
```

编译好的jar包在各个submodule的target目录中。如果你想要在自己的项目中使用你自己编译的jar包作为依赖，建议不要使用systemPath的方式引入（容易出现`ClassNotFoundException`，需要处理Protobuf等依赖包的编译运行问题）。更好的方式是，通过`mvn install -DskipTests=true -Dscalatest.skip=true -Dwagon.skip=true -Dmaven.test.skip=true -Dgpg.skip`安装到本地m2仓库，再使用它们。

## 针对特征工程优化的 OpenMLDB Spark 发行版

[OpenMLDB Spark 发行版](https://github.com/4paradigm/spark)是 [Apache Spark](https://github.com/apache/spark) 的定制发行版。它针对机器学习场景提供特定优化，包括达到10倍到100倍性能提升的原生 LastJoin 实现。你可以使用和标准 Spark 一样的 Java/Scala/Python/SQL 接口，来使用 OpenMLDB Spark 发行版。

注意：为了运行 OpenMLDB 的定制化 SQL 语法，你必须使用该 OpenMLDB Spark 发行版本。

1. 下载预编译的OpenMLDB Spark发行版。

```bash
wget https://github.com/4paradigm/spark/releases/download/v3.2.1-openmldb0.9.0/spark-3.2.1-bin-openmldbspark.tgz
```

或者下载源代码并从头开始编译。

```bash
git clone https://github.com/4paradigm/spark.git
cd ./spark/
./dev/make-distribution.sh --name openmldbspark --pip --tgz -Phadoop-2.7 -Pyarn -Pallinone -Phive -Phive-thriftserver
```

2. 设置环境变量 `SPARK_HOME` 来使用 OpenMLDB Spark 的发行版本来运行 OpenMLDB 或者其他应用。

```bash
tar xzvf ./spark-3.2.1-bin-openmldbspark.tgz
cd spark-3.2.1-bin-openmldbspark/
export SPARK_HOME=`pwd`
```

3. 你现在可以正常使用 OpenMLDB 了，同时享受由定制化的 Spark 所带来的的性能提升体验。

## 快速编译适配其他平台

如前文所述，如果你想要在其他平台运行 OpenMLDB 或 SDK，需要从源码编译。我们为以下几个平台，提供了快速编译的解决方案，其他少见的平台请自行源码编译。

### Centos 6等低版本glibc Linux OS

#### 本地编译

本地编译centos6适配的版本，可以使用Docker和脚本`steps/centos6_build.sh`。如下所示，我们使用当前目录作为挂载目录，将编译产出放在本地。

```bash

```bash
git clone https://github.com/4paradigm/OpenMLDB.git
cd OpenMLDB
docker run -it -v`pwd`:/root/OpenMLDB ghcr.io/4paradigm/centos6_gcc7_hybridsql bash
```

在容器内执行编译脚本，编译产出在`build`目录下。如果编译中下载`bazel`或`icu4c`失败，可以使用OpenMLDB提供的镜像源，配置环境变量`OPENMLDB_SOURCE=true`即可。make可使用的各个环境变量同样生效，如下所示。

```bash
cd OpenMLDB
bash steps/centos6_build.sh
# THIRD_PARTY_CMAKE_FLAGS=-DMAKEOPTS=-j8 bash steps/centos6_build.sh # run fast when build single project
# OPENMLDB_SOURCE=true bash steps/centos6_build.sh
# SQL_JAVASDK_ENABLE=ON SQL_PYSDK_ENABLE=ON NPROC=8 bash steps/centos6_build.sh # NPROC will build openmldb in parallel, thirdparty should use THIRD_PARTY_CMAKE_FLAGS
```

本地2.20GHz CPU，SSD硬盘，32线程编译三方库与OpenMLDB主体，耗时参考：
`THIRD_PARTY_CMAKE_FLAGS=-DMAKEOPTS=-j32 SQL_JAVASDK_ENABLE=ON SQL_PYSDK_ENABLE=ON NPROC=32 bash steps/centos6_build.sh`
- thirdparty（不包括下载src时间）~40m：zetasql打patch 13m，所有thirdparty编译30m
- OpenMLDB 本体，包括python和java native，~12min

#### 云编译

Fork OpenMLDB仓库后，可以使用在`Actions`中触发workflow `Other OS Build`，编译产出在`Actions`的`Artifacts`中。workflow 配置方式：
- 不要更换`Use workflow from`为某个tag，可以是其他分支。
- 选择`os name`为`centos6`。
- 如果不是编译main分支，在`The branch, tag or SHA to checkout, otherwise use the branch`中填写想要的分支名、Tag(e.g. v0.9.0)或SHA。
- 编译产出在触发后的runs界面中，参考[成功产出的runs链接](https://github.com/4paradigm/OpenMLDB/actions/runs/6044951902)。
  - 一定会产出openmldb binary文件。
  - 如果不需要Java或Python SDK，可配置`java sdk enable`或`python sdk enable`为`OFF`，节约编译时间。

此编译流程需要从源码编译thirdparty，且资源较少，无法开启较高的并发编译。因此编译时间较长，大约需要3h5m（2h thirdparty+1h OpenMLDB）。workflow会缓存thirdparty的编译产出，因此第二次编译会快很多（1h15m OpenMLDB）。

### Linux for ARM64

支持在 AArch64 架构的 Linux 系统上编译, 建议选择编译镜像 `ghcr.io/4paradigm/hybridsql` 在容器内编译. 在容器内:

```sh
# 建议在编译镜像内进行
docker run -it ghcr.io/4paradigm/hybridsql:latest
 
# inside docker container
git clone https://github.com/4paradigm/OpenMLDB
cd OpenMLDB
 
# 安装 third-party 编译 deps
yum install -y flex autoconf automake unzip bc expect libtool \
    rh-python38-python-devel gettext byacc xz tcl cppunit-devel rh-python38-python-wheel patch java-1.8.0-openjdk-devel
# bazel
curl --create-dirs -SLo /usr/local/bin/bazel https://github.com/bazelbuild/bazelisk/releases/download/v1.19.0/bazelisk-linux-arm64
chmod +x /usr/local/bin/bazel
 
# third-party
cmake -S third-party -B .deps -DBUILD_BUNDELD=ON -DMAKEOPTS=-j$(nproc)
cmake --build .deps
 
# OpenMLDB source
cmake -S . -B build -DCMKAE_PREFIX_PATH=$(pwd)/.deps/usr -DSQL_JAVASDK_ENABLE=ON -DSQL_PYSDK_ENABLE=ON
cmake --build build -- -j$(nproc)
```

### Macos 10.15, 11

Macos适配不需要从源码编译thirdparty，所以云编译耗时不会太长，大约1h15m。本地编译与[从源码全量编译](#从源码全量编译)章节相同，无需编译thirdparty（`BUILD_BUNDLED=OFF`）。云编译需要在`Actions`中触发workflow `Other OS Build`，编译产出在`Actions`的`Artifacts`中。workflow 配置 `os name`为`macos10`/`macos11`，同样可配置`java sdk enable`或`python sdk enable`为`OFF`。