diff --git a/docs/README.md b/docs/README.md index e2d7b64b1..f4e73fe11 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,8 +10,8 @@ At present, the guide is composed of the following parts: 1. **Get started**: Setting up the development environment, build and connect to the OceanBase server, the subsections are based on an imagined newbie user journey. - 1. Install toolchain - 2. Get the code, build and run + 1. [Install toolchain](toolchain.md) + 2. [Get the code, build and run](build-and-run.md) 3. Set up an IDE 4. Write and run unit tests 5. Debug and profile diff --git a/docs/build-and-run.md b/docs/build-and-run.md new file mode 100644 index 000000000..a763f698c --- /dev/null +++ b/docs/build-and-run.md @@ -0,0 +1,71 @@ +# Get the code, build and run + +## Prerequisites + +Check the [Install toolchain](toolchain.md) guide for supported OS, GLIBC version requirement, and how to install the C++ toolchain. + +## Clone + +Clone the source code to your development machine: + +```shell +git clone https://github.com/oceanbase/oceanbase.git +``` + +## Build + +Build OceanBase from the source code in debug mode or release mode: + +### Debug mode + +```shell +bash build.sh debug --init --make +``` + +### Release mode + +```shell +bash build.sh release --init --make +``` + +## Run + +Now that you built the `observer` binary, you can deploy a OceanBase instance with the `obd.sh` utility: + +```shell +./tools/deploy/obd.sh prepare -p /tmp/obtest +./tools/deploy/obd.sh deploy -c single.yaml +``` + +This starts the OceanBase server listening on port 10000. + +## Connect + +You can use the official MySQL client to connect to OceanBase: + +```shell +mysql -uroot -h127.0.0.1 -P10000 +``` + +Alternatively, you can use the `obclient` to connect to OceanBase: + +```shell +./deps/3rd/u01/obclient/bin/obclient -h127.0.0.1 -P10000 -uroot -Doceanbase +``` + +## Shutdown + +You can run the following command to shut down the server and clean up the deployment, which prevents disk consuming: + +```shell +./tools/deploy/obd.sh destroy --rm -n single +``` + +## Bonus: RPM packages + +You can build OceanBase RPM packages on Fedora based OS: + +```shell +sudo yum install rpm-build +bash build.sh rpm --init && cd build_rpm && make -j16 rpm +``` diff --git a/docs/toolchain.md b/docs/toolchain.md new file mode 100644 index 000000000..c28b5eac2 --- /dev/null +++ b/docs/toolchain.md @@ -0,0 +1,59 @@ +# Install toolchain + +To build OceanBase from source code, you need to install the C++ toolchain in your development environment first. If the C++ toolchain is not installed yet, you can follow the instructions in this document for installation. + +## Supported OS + +OceanBase makes strong assumption on the underlying operator systems. Not all the operator systems are supported; especially, Windows and Mac OS X are not supported yet. + +Below is the OS compatiblity list: + +| OS | Version | Arch | Compilable | Package Deployable | Compiled Binary Deployable | MYSQLTEST Passed | +| ------------------- | --------------------- | ------ | ---------- | ------------------ | -------------------------- | ---------------- | +| Alibaba Cloud Linux | 2.1903 | x86_64 | Yes | Yes | Yes | Yes | +| CentOS | 7.2 / 8.3 | x86_64 | Yes | Yes | Yes | Yes | +| Debian | 9.8 / 10.9 | x86_84 | Yes | Yes | Yes | Yes | +| Fedora | 33 | x86_84 | Yes | Yes | Yes | Yes | +| openSUSE | 15.2 | x86_84 | Yes | Yes | Yes | Yes | +| OpenAnolis | 8.2 | x86_84 | Yes | Yes | Yes | Yes | +| StreamOS | 3.4.8 | x86_84 | Unknown | Yes | Yes | Unknown | +| SUSE | 15.2 | x86_84 | Yes | Yes | Yes | Yes | +| Ubuntu | 16.04 / 18.04 / 20.04 | x86_84 | Yes | Yes | Yes | Yes | + +> **Note**: +> +> Other Linux distributions _may_ work. If you verify that OceanBase can compile and deploy on a distribution except ones listed above, feel free to submit a pull request to add it. + +## Supported GLIBC + +OceanBase and its dependencies dynamically link to The GNU C Library (GLIBC). And the version of GLIBC share library is restrict to be less than or equal to 2.34. + +See [ISSUE-1337](https://github.com/oceanbase/oceanbase/issues/1337) for more details. + +## Installation + +The installation instructions vary among the operator systems and package managers you develop with. Below are the instructions for some popular environments: + +### Fedora based + +This includes CentOS, Fedora, OpenAnolis, RedHat, UOS, etc. + +```shell +yum install git wget rpm* cpio make glibc-devel glibc-headers binutils m4 +``` + +### Debian based + +This includes Debian, Ubuntu, etc. + +```shell +apt-get install git wget rpm rpm2cpio cpio make build-essential binutils m4 +``` + +### SUSE based + +This includes SUSE, openSUSE, etc. + +```shell +zypper install git wget rpm cpio make glibc-devel binutils m4 +```