Clone repository và chọn phiên bản Seastar
Tải source code từ GitHub
Chúng ta cần lấy mã nguồn từ repository chính thức của Facebook (Meta). Việc này đảm bảo bạn có bản code mới nhất và đầy đủ nhất.
Thực hiện clone repository về thư mục làm việc. Sau đó, chuyển vào thư mục vừa clone để kiểm tra.
git clone https://github.com/scylladb/seastar.git
cd seastar
Kết quả mong đợi: Bạn thấy thư mục `seastar` được tạo ra và hiện tại bạn đang đứng trong thư mục gốc của dự án.
Chọn tag phiên bản ổn định
Để đảm bảo tính ổn định cho môi trường production, không nên build từ branch `main` (vốn có thể chứa code chưa ổn định). Chúng ta sẽ checkout về một tag release cụ thể. Hiện tại, tag `2024.1.0` hoặc `2023.x.x` là các bản ổn định phổ biến.
Lệnh dưới đây sẽ chuyển trạng thái của repository về tag `2024.1.0` (hoặc tag mới nhất có sẵn nếu bạn muốn, nhưng tôi khuyên dùng tag cụ thể để dễ reproduce).
git fetch --tags
git checkout 2024.1.0
Kết quả mong đợi: Thông báo `HEAD is now at ` xác nhận bạn đang ở đúng phiên bản cần thiết.
Cấu hình build với Ninja và tối ưu hóa Release
Chạy script cấu hình build
Seastar sử dụng `cmake` để tạo ra file cấu hình cho `ninja`. Chúng ta cần tạo một thư mục riêng biệt cho build (out-of-source build) để giữ sạch thư mục source code.
Tùy chọn `-DCMAKE_BUILD_TYPE=Release` là bắt buộc để kích hoạt các tối ưu hóa compiler (O3, LTO) cần thiết cho hiệu năng I/O cao. Tùy chọn `-DSEASTAR_ENABLE_PYTHON=OFF` giúp giảm bớt phụ thuộc nếu bạn chỉ cần thư viện C++.
mkdir build
cd build
../configure.py --mode=release --enable-python=no
Kết quả mong đợi: Script chạy qua, thông báo "Build directory: build" và tạo ra file `build.ninja` cùng các file config khác trong thư mục này.
Giải thích các tham số cấu hình
Tham số `--mode=release` kích hoạt các cờ biên dịch như `-O3`, `-DNDEBUG` để loại bỏ các kiểm tra debug, tăng tốc độ chạy đáng kể.
Tham số `--enable-python=no` tắt module Python binding, giúp giảm thời gian build và kích thước thư viện nếu bạn không cần gọi Seastar từ Python.
Nếu bạn muốn bật thêm các tính năng đặc biệt như hỗ trợ `io_uring` (tự động được bật trên kernel mới) hoặc `systemtap`, bạn có thể thêm `--enable-systemtap=yes` vào lệnh trên.
Biên dịch bằng Ninja và xử lý lỗi
Thực hiện biên dịch song song
Sử dụng `ninja` để biên dịch. Chúng ta sẽ tận dụng tất cả các core CPU có sẵn để giảm thời gian build. Số lượng job (-j) nên bằng số logical core của CPU.
Lệnh dưới đây tự động lấy số core và chạy build.
ninja -j$(nproc)
Kết quả mong đợi: Quá trình biên dịch diễn ra nhanh chóng. Khi xong, dòng cuối cùng sẽ là `ninja: build succeeded`.
Xử lý lỗi thiếu dependency
Nếu quá trình build bị lỗi với thông báo `Could NOT find ...` hoặc `fatal error: ...: No such file or directory`, thường là do thiếu thư viện hệ thống cần thiết.
Trên Ubuntu 24.04, nếu gặp lỗi liên quan đến `fmt` hoặc `boost`, hãy cài đặt lại các package sau:
sudo apt-get update
sudo apt-get install -y libboost-all-dev libfmt-dev libssl-dev libnumactl-dev
Sau khi cài đặt, quay lại thư mục build và chạy lại lệnh build:
cd ../build
ninja -j$(nproc)
Kết quả mong đợi: Lỗi build được khắc phục và quá trình biên dịch hoàn tất thành công.
Xử lý lỗi liên quan đến Kernel (io_uring)
Seastar sử dụng `io_uring` để tối ưu I/O. Nếu kernel của bạn quá cũ hoặc không hỗ trợ đầy đủ, build có thể báo cảnh báo hoặc lỗi liên quan đến header file.
Trên Ubuntu 24.04, kernel mặc định (6.8+) hỗ trợ đầy đủ. Nếu bạn dùng kernel cũ hơn, bạn có thể tắt hỗ trợ io_uring bằng cách chạy lại configure với `--disable-io-uring=yes` (không khuyến khích trên Ubuntu 24.04).
Kiểm tra và cài đặt thư viện vào hệ thống
Chạy bộ test đơn vị (Unit Tests)
Trước khi cài đặt, hãy đảm bảo thư viện hoạt động chính xác bằng cách chạy bộ test đi kèm. Điều này xác nhận quá trình build không bị lỗi logic.
ctest --output-on-failure
Kết quả mong đợi: Thông báo `Test summary: 100% passed`. Nếu có test fail, hãy xem log lỗi để debug trước khi cài đặt.
Cài đặt thư viện và header vào thư mục hệ thống
Để các project khác có thể liên kết (link) với Seastar, chúng ta cần cài đặt thư viện `.so` và file header vào các thư mục chuẩn của Linux (`/usr/local/lib`, `/usr/local/include`).
Lệnh `ninja install` sẽ thực hiện việc này. Bạn cần quyền `sudo` để ghi vào thư mục hệ thống.
sudo ninja install
Kết quả mong đợi: Các file được copy vào `/usr/local/`. Bạn sẽ thấy thông báo `Install the project... -- Install configuration: "Release"`.
Cập nhật cache thư viện động (ldconfig)
Sau khi cài đặt thư viện `.so`, trình liên kết động (dynamic linker) cần được thông báo để biết vị trí mới của thư viện. Nếu bỏ qua bước này, các ứng dụng khác sẽ không tìm thấy thư viện Seastar.
sudo ldconfig
Kết quả mong đợi: Không có output (im lặng) là thành công. Nếu có lỗi, hãy kiểm tra lại đường dẫn trong `/etc/ld.so.conf.d/`.
Verify kết quả cài đặt
Để chắc chắn Seastar đã được cài đặt đúng, chúng ta sẽ kiểm tra xem trình liên kết có nhận diện được thư viện hay không.
ldconfig -p | grep seastar
Kết quả mong đợi: Bạn thấy dòng hiển thị đường dẫn đầy đủ đến thư viện, ví dụ: `libseastar.so (libc6,x86-64) => /usr/local/lib/libseastar.so`.
Kiểm tra thêm file header:
ls /usr/local/include/seastar/core/app-template.hh
Kết quả mong đợi: File `app-template.hh` tồn tại, xác nhận các file header đã được copy đúng vị trí.
Điều hướng series:
Mục lục: Series: Triển khai Database Log-Structured với Seastar trên Ubuntu 24.04
« Phần 1: Chuẩn bị môi trường Ubuntu 24.04 và công cụ xây dựng cho Seastar
Phần 3: Khái niệm cơ bản về Log-Structured Storage và kiến trúc Seastar »