OceanBase Developer Handbook, Part 2: How to Set Up the IDE Development Environment

Abstract

The “OceanBase Developer Handbook” mainly guides developers on how to get involved in OceanBase development, smoothing out the preparatory hurdles you may encounter when participating in OceanBase development. This series currently consists of roughly the following articles, with more possibly added in the future. For now, OceanBase source code references the “Open Source Database OceanBase Source Code Walkthrough” series on the OceanBase open source official site:

1. How to compile OceanBase source code
2. How to set up the IDE development environment
3. How to become an OceanBase Contributor
4. How to modify OceanBase documentation
5. How to debug OceanBase
6. How to run tests
7. How to fix bugs
   ​

This article explains how to set up the compiler in your development environment, with a focus on setting up the compiler’s code format tool — clang-format. The content here comes from an internal colleague’s sharing, and these settings can be applied to all C/C++ projects.

clang-format is a tool within clang (a lightweight compiler for C-family languages). It is mainly responsible for code formatting and layout, can work independently of clang, and is therefore often used on its own for code-style formatting. Many third-party plugins also integrate clang-format. clang-format integrates with various IDEs, and it has pretty much become the de facto real-time code-formatting standard on C/C++.

​

Steps

vscode

Since you’ve gotten this far, I’ll just assume you’ve already installed vscode. If not, head over to the vscode official site to download it first.

STEP 1

First, make sure the vscode in your development environment has the C/C++ extension installed;

Note that the vscode remote and local vscode plugins are not shared.

STEP 2

In the settings, configure Clang_format_style, making sure the C/C++ extension’s Clang_format_style setting is set to file (it defaults to file here; if you’re not sure, you can check it);

STEP 3

Copy the prepared .clang-format file into the project directory (in some projects it already exists in the project directory).

STEP FINAL

Congratulations, you’ve completed the clang-format setup in vscode. If you’ve finished all the above, then when you format code in vscode it will automatically format the file according to the .clang-format configuration.

eclipse

STEP 1

First, you need to download clang-format in your development environment (a wget package download or some other more general method will be provided later when this is rolled out).

$brew install clang-format

Alternatively, you can download the entire LLVM and find clang-format in its directory, then note down the path to clang-format.
On Linux/Mac, it’s best to copy it to the /usr/bin directory so it can be executed directly as a command.

After running $OBDEV_ROOT/build.sh –init, clang-format will be downloaded automatically, and you can find it here:

find ./ -name clang-format
./deps/3rd/usr/local/oceanbase/devtools/bin/clang-format

STEP 2

Install the CppStyle plugin in eclipse.

STEP 3

Configure the clang-format path in CppStyle:

(If your CppStyle plugin installed successfully and you restarted, this configuration option will be present.)
Preferences -> C/C++ -> CppStyle 

Set the clang-format path you downloaded earlier in the Clang-format path field.

STEP 4

Set Code Formatter to CppStyle:

Preferences -> C/C++ -> Code Style -> Formatter

In the Code Formatter dropdown, select CppStyle(clang-format) (if you completed the previous steps correctly, this option should be available here).

STEP 5

Copy the prepared .clang-format file into the project directory (in some projects it already exists in the project directory).

STEP FINAL

At this point you’ve completed all the preparation. When you write code in eclipse and format it, it will automatically reference the .clang-format configuration to re-arrange the code.

CLion

Ah, finally an easy one to write a guide for. JetBrains is the GOAT!
CLion integrates clang-format natively, so you only need to confirm a few settings.

STEP 1

Open any .h/.c/.cpp file, click ‘4 spaces’ in the bottom-right corner, and select Enable ClangFormat.

If instead of ‘4 spaces’ you directly see ClangFormat here, then CLion has automatically detected the presence of a .clang-format file and configured it for you.

STEP 2

Confirm whether the ‘Enable ClangFormat’ setting is turned on (CLion also enables this by default).

Preferences -> Editor -> Code Style

STEP 3

Copy the prepared .clang-format file into the project directory (in some projects it already exists in the project directory).

STEP FINAL

CLion can then use clang-format for formatting directly. When you run Reformat Code, it will automatically rearrange the code.

VIM

STEP 1

First, you need the clang-format.py file. We can copy the corresponding file directly from GitHub.

STEP 2

Then configure the current user’s .vimrc file (if it doesn’t exist, just create a .vimrc file in the current user’s home directory).

map <C-K> :pyf <path-to-this-file>/clang-format.py<cr>
imap <C-K> <c-o>:pyf <path-to-this-file>/clang-format.py<cr>

function! Formatonsave()
  let l:formatdiff = 1
  pyf <path-to-this-file>/clang-format.py
endfunction
autocmd BufWritePre *.h,*.cc,*.cpp call Formatonsave()

Replace ‘‘ in the code block with the path to the clang-format.py you copied earlier, then save and restart the terminal.

PS: The first two lines add the ability to manually trigger clang-format.

In normal mode, ctrl+k formats one line of code.
In visual mode, ctrl+k formats the selected code.
In insert mode, ctrl+k formats one line of code.

The function in the last section automatically formats the entire contents of the file when you use vim to save the current .h/.cc/.cpp file.

STEP 3

Copy the prepared .clang-format file into the project directory (in some projects it already exists in the project directory).

STEP FINAL

After completing the above, vim has successfully integrated clang-format. Just note that when using it, you first need to cd into the project path and make sure a .clang-format file already exists in the project path, then edit files with vim under that path (don’t switch the current directory while using vim).

EMACS

EMACS seems to be a very powerful editor (I’m not even sure whether it should be called an editor), but the learning curve is a bit steep for newcomers. I fiddled with it for a whole evening before barely getting it working 😅
If you’re reading this section, I’ll assume you already understand some basic Emacs operations. Expanding on that could fill an entire series on its own, so here I’ll only lay out the operations related to clang-format integration and won’t go into the rest.

STEP 1

First, you need to download clang-format in your development environment (a wget package download or some other more general method will be provided later when this is rolled out).

brew install clang-format

Alternatively, you can download the entire LLVM and find clang-format in its directory.
On Linux, you need to copy it to the /usr/bin directory.
On macOS, you also need to configure it in the corresponding PATH.

After running $OBDEV_ROOT/build.sh –init, clang-format will be downloaded automatically, and you can find it here:

find ./ -name clang-format
./deps/3rd/usr/local/oceanbase/devtools/bin/clang-format

STEP 2

Then you need to use package-install to install the clang-format package. If it’s not available, you can modify the package sources. Here’s the sources configuration I use:

("melpa" . "http://mirrors.tuna.tsinghua.edu.cn/elpa/melpa/")
("org-cn" . "http://mirrors.tuna.tsinghua.edu.cn/elpa/org/")
("gnu" . "http://mirrors.tuna.tsinghua.edu.cn/elpa/gnu/")

STEP 3

After installation, find the location of the installed plugin. I’m on a Mac, and it’s installed in the user’s home directory.

.emacs.d/elpa/clang-format-20191106.950

Find the clang-format.el file under that path, and configure that file’s path into the .emacs config file (adjust the config path according to your actual situation):

(load "/Users/xxx/.emacs.d/elpa/clang-format-20191106.950/clang-format.el")

PS: On a Mac it’s a bit more troublesome. When you open Emacs via the GUI on macOS, the environment variables configured in the shell are not automatically carried over. In that case, you need to add some extra content to .emacs:

(defun set-exec-path-from-shell-PATH ()
  "Set up Emacs' `exec-path' and PATH environment variable to match
that used by the user's shell.

This is particularly useful under Mac OS X and macOS, where GUI
apps are not started from a shell."
  (interactive)
  (let ((path-from-shell (replace-regexp-in-string
        "[ \t\n]*$" "" (shell-command-to-string
            "$SHELL --login -c 'echo $PATH'"
                ))))
    (setenv "PATH" path-from-shell)
    (setq exec-path (split-string path-from-shell path-separator))))

(set-exec-path-from-shell-PATH)

STEP 4

Copy the prepared .clang-format file into the project directory (in some projects it already exists in the project directory).

STEP FINAL

Now you’ve completed the clang-format integration. During development, you just need to run M-x clang-format-buffer in the file editing view. clang-format will then automatically look up the directory tree from the current level to parent directories to find the .clang-format file and format the code according to its configuration.