Building from source code in macOS

This document will guide you to deploy a standalone version of MatrixOne in a macOS environment using source code. You can use the mo_ctl tool to help you deploy and manage MatrixOne.

MatrixOne supports x86 and ARM macOS systems. This article uses the Macbook M1 ARM version as an example to show the entire deployment process.

Pre-dependency Reference

To install and use the stand-alone MatrixOne through source code, you need to depend on the following software packages.

Dependent softwareVersion
golang1.20 or later
gcc/clanggcc8.5 or later, clang13.0 or later
git2.20 or later
MySQL Client8.0 or later

Step 1: Install Dependency

1. Install Go

  1. Click Go Download and install to enter its official documentation, and follow the installation steps to complete the Go installation.

  2. To verify whether Go is installed, please execute the code go version. When Go is installed successfully, the example code line is as follows:

    1. > go version
    2. go version go1.20.5 darwin/arm64

2. Install GCC/Clang

  1. macOS generally has its own Clang compiler, which plays the same role as GCC. To verify whether the GCC is installed:

    1. gcc -v
    2. bash: gcc: command not found

    As shown in the code, the version of GCC is not displayed, the GCC/Clang environment needs to be installed.

  2. Click GCC Download and install to enter its official documentation, and follow the installation steps to complete the GCC installation. Or you can install Clang through Apple’s official Xcode.

  3. To verify whether GCC/Clang is installed, please execute the code gcc -v. When GCC is installed successfully, the example code line is as follows:

    1. Apple clang version 14.0.3 (clang-1403.0.22.14.1)
    2. Target: arm64-apple-darwin22.5.0
    3. Thread model: posix
    4. InstalledDir: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin

3. Install Git

Install Git via the Official Documentation.

Use the command git version to check whether the installation is successful. The code example of a successful installation is as follows:

  1. > git version
  2. git version 2.40.0

4. Install and configure MySQL Client

  1. Click MySQL Community Downloads to enter into the MySQL client download and installation page. According to your operating system and hardware environment, drop down to select Select Operating System > macOS, then drop down to select Select OS Version, and select the download installation package to install as needed.

  2. Configure the MySQL client environment variables:

    1. Open a new terminal window and enter the following command:

      1. cd ~
      2. sudo vim .bash_profile

    2. After pressing Enter on the keyboard to execute the above command, you need to enter the root user password, which is the root password you set in the installation window when you installed the MySQL client. If no password has been set, press Enter to skip the password.

    3. After entering/skiping the root password, you will enter .bash_profile, click i on the keyboard to enter the insert state, and you can enter the following command at the bottom of the file:

      1. export PATH=${PATH}:/usr/local/mysql/bin

  3. After the input is completed, click esc on the keyboard to exit the insert state, and enter :wq at the bottom to save and exit.

  4. Enter the command source .bash_profile, press Enter to execute, and run the environment variable.

  5. To test whether MySQL is available:

    Run the command mysql --version, if MySQL client is installed successfully, the example code line is as follows: mysql Ver 8.0.31 for macos12 on arm64 (MySQL Community Server - GPL)

Step 2: Install the mo_ctl tool

mo_ctl is a command-line tool for deploying, installing, and managing MatrixOne. It is very convenient to perform various operations on MatrixOne. See mo_ctl Tool for complete usage details.

  1. First, install the wget download tool: Go to the Homebrew page and follow the steps to install Homebrew first, then install wget. To verify whether wget is installed successfully, you can use the following command line:

    1. wget -V

    The successful installation results (only part of the code is displayed) are as follows:

    1. GNU Wget 1.21.3 在 darwin21.3.0 上编译
    2. ...
    3. Copyright © 2015 Free Software Foundation, Inc.
    4. ...

  2. The mo_ctl tool can be installed through the following command:

    1. wget https://raw.githubusercontent.com/matrixorigin/mo_ctl_standalone/main/install.sh && sudo -u $(whoami) bash +x ./install.sh

  3. After the installation is complete, verify whether the installation is successful through the mo_ctl command:

    1. > mo_ctl
    2. Usage             : mo_ctl [option_1] [option_2]
    4. [option_1]      : available: connect | ddl_connect | deploy | get_branch | get_cid | get_conf | help | pprof | precheck | restart | set_conf | sql | start | status | stop | uninstall | upgrade | watchdog
    5. 1) connect      : connect to mo via mysql client using connection info configured
    6. 2) ddl_convert  : convert ddl file to mo format from other types of database
    7. 3) deploy       : deploy mo onto the path configured
    8. 4) get_branch   : upgrade or downgrade mo from current version to a target commit id or stable version
    9. 5) get_cid      : print mo git commit id from the path configured
    10. 6) get_conf     : get configurations
    11. 7) help         : print help information
    12. 8) pprof        : collect pprof information
    13. 9) precheck     : check pre-requisites for mo_ctl
    14. 10) restart     : a combination operation of stop and start
    15. 11) set_conf    : set configurations
    16. 12) sql         : execute sql from string, or a file or a path containg multiple files
    17. 13) start       : start mo-service from the path configured
    18. 14) status      : check if there's any mo process running on this machine
    19. 15) stop        : stop all mo-service processes found on this machine
    20. 16) uninstall   : uninstall mo from path MO_PATH=/data/mo//matrixone
    21. 17) upgrade     : upgrade or downgrade mo from current version to a target commit id or stable version
    22. 18) watchdog    : setup a watchdog crontab task for mo-service to keep it alive
    23. e.g.            : mo_ctl status
    24. [option_2]      : Use " mo_ctl [option_1] help " to get more info
    25. e.g.            : mo_ctl deploy help

Set mo_ctl parameters (Optional)

Some parameters in the mo_ctl tool need to be set and you can view all current parameters through mo_ctl get_conf.

  1. > mo_ctl get_conf
  2. 2023-07-07_15:31:24    [INFO]    Below are all configurations set in conf file /Users/username/mo_ctl/conf/env.sh
  3. MO_PATH="/Users/username/mo/matrixone"
  4. MO_LOG_PATH="${MO_PATH}/matrixone/logs"
  5. MO_HOST="127.0.0.1"
  6. MO_PORT="6001"
  7. MO_USER="root"
  8. MO_PW="111"
  9. MO_DEPLOY_MODE="host"
  10. MO_REPO="matrixorigin/matrixone"
  11. MO_IMAGE_PREFIX="nightly"
  12. MO_IMAGE_FULL=""
  13. MO_CONTAINER_NAME="mo"
  14. MO_CONTAINER_PORT="6001"
  15. MO_CONTAINER_DEBUG_PORT="12345"
  16. CHECK_LIST=("go" "gcc" "git" "mysql" "docker")
  17. GCC_VERSION="8.5.0"
  18. CLANG_VERSION="13.0"
  19. GO_VERSION="1.20"
  20. MO_GIT_URL="https://github.com/matrixorigin/matrixone.git"
  21. MO_DEFAULT_VERSION="v1.1.0"
  22. GOPROXY="https://goproxy.cn,direct"
  23. STOP_INTERVAL="5"
  24. START_INTERVAL="2"
  25. MO_DEBUG_PORT="9876"
  26. MO_CONF_FILE="${MO_PATH}/matrixone/etc/launch/launch.toml"
  27. RESTART_INTERVAL="2"
  28. PPROF_OUT_PATH="/tmp/pprof-test/"
  29. PPROF_PROFILE_DURATION="30"

Generally, the parameters that may need to be adjusted are as follows:

  1. mo_ctl set_conf MO_PATH="/Users/username/mo/matrixone" # Set custom MatrixOne download path
  2. mo_ctl set_conf MO_GIT_URL="https://ghproxy.com/https://github.com/matrixorigin/matrixone.git" ## For the problem of slow downloading from the original GitHub address, set the proxy download address
  3. mo_ctl set_conf MO_DEFAULT_VERSION="v1.1.0" # Set the version of MatrixOne downloaded

Step 3: Get MatrixOne code

Depending on your needs, choose whether you want to keep your code up to date, or if you want to get the latest stable version of the code.

Get the MatrixOne(Develop Version) code to buildGet the MatrixOne(Stable Version) code to build

The main branch is the default branch, the code on the main branch is always up-to-date but not stable enough.

  1. mo_ctl deploy main
  1. mo_ctl deploy v1.1.0

Step 4: Launch MatrixOne server

Launch the MatrixOne service through the mo_ctl start command.

If the operation is regular, the following log will appear. The relevant operation logs of MatrixOne will be in /data/mo/logs/.

  1. > mo_ctl start
  2. 2023-07-07_15:33:45    [INFO]    No mo-service is running
  3. 2023-07-07_15:33:45    [INFO]    Starting mo-service: cd /Users/username/mo/matrixone/matrixone/ && /Users/username/mo/matrixone/matrixone/mo-service -daemon -debug-http :9876 -launch /Users/username/mo/matrixone/matrixone/etc/launch/launch.toml >/Users/username/mo/matrixone/matrixone/logs/stdout-20230707_153345.log 2>/Users/username/mo/matrixone/matrixone/logs/stderr-20230707_153345.log
  4. 2023-07-07_15:33:45    [INFO]    Wait for 2 seconds
  5. 2023-07-07_15:33:48    [INFO]    At least one mo-service is running. Process info:
  6. 2023-07-07_15:33:48    [INFO]      501 66932     1   0  3:33PM ??         0:00.27 /Users/username/mo/matrixone/matrixone/mo-service -daemon -debug-http :9876 -launch /Users/username/mo/matrixone/matrixone/etc/launch/launch.toml
  7. 2023-07-07_15:33:48    [INFO]    Pids:
  8. 2023-07-07_15:33:48    [INFO]    66932
  9. 2023-07-07_15:33:48    [INFO]    Start succeeded

Note

The initial startup of MatrixOne approximately takes 20 to 30 seconds. After a brief wait, you can connect to MatrixOne using the MySQL client.

Step 5: Connect to MatrixOne

One-click connection to MatrixOne service through mo_ctl connect command.

This command will invoke the MySQL Client tool to connect to the MatrixOne service automatically.

  1. > mo_ctl connect
  2. 2023-07-07_10:30:20    [INFO]    Checking connectivity
  3. 2023-07-07_10:30:20    [INFO]    Ok, connecting for user ...
  4. mysql: [Warning] Using a password on the command line interface can be insecure.
  5. Welcome to the MySQL monitor.  Commands end with ; or \g.
  6. Your MySQL connection id is 15
  7. Server version: 8.0.30-MatrixOne-v1.1.0 MatrixOne
  9. Copyright (c) 2000, 2023, Oracle and/or its affiliates.
  11. Oracle is a registered trademark of Oracle Corporation and/or its
  12. affiliates. Other names may be trademarks of their respective
  13. owners.
  15. Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
  17. mysql>

Note

The above connection and login account is the initial accounts root and the password 111; please change the initial password after logging in to MatrixOne; see MatrixOne Password Management. After changing the login username or password, you must set a new username and password through mo_ctl set_conf. For details, please refer to mo_ctl Tool.