Hướng dẫn này sử dụng tình huống ví dụ để mô tả cách định cấu hình chuỗi công cụ C++ cho một dự án. Thư viện này dựa trên một dự án C++ mẫu để tạo bản dựng mà không có lỗi bằng clang
.
Kiến thức bạn sẽ học được
Trong hướng dẫn này, bạn tìm hiểu cách:
- Thiết lập môi trường tạo bản dựng
- Định cấu hình chuỗi công cụ C++
- Tạo một quy tắc Starlark cung cấp cấu hình bổ sung cho
cc_toolchain
để Bazel có thể tạo ứng dụng bằngclang
- Xác nhận kết quả dự kiến bằng cách chạy
bazel build --config=clang_config //main:hello-world
trên máy Linux - Xây dựng ứng dụng C++
Trước khi bắt đầu
Thiết lập môi trường tạo bản dựng
Hướng dẫn này giả định rằng bạn đang sử dụng Linux và đã tạo thành công các ứng dụng C++, đồng thời cài đặt các công cụ và thư viện thích hợp.
Phần hướng dẫn sử dụng clang version 9.0.1
mà bạn có thể cài đặt trên hệ thống của mình.
Thiết lập môi trường tạo bản dựng như sau:
Nếu bạn chưa thực hiện thao tác này, hãy tải xuống và cài đặt Bazel 0.23 trở lên.
Tải dự án C++ mẫu xuống từ GitHub và đặt dự án đó vào một thư mục trống trên máy cục bộ.
Thêm mục tiêu
cc_binary
sau vào tệpmain/BUILD
:cc_binary( name = "hello-world", srcs = ["hello-world.cc"], )
Tạo một tệp
.bazelrc
ở gốc của thư mục không gian làm việc có nội dung sau để cho phép sử dụng cờ--config
:# Use our custom-configured c++ toolchain. build:clang_config --crosstool_top=//toolchain:clang_suite # Use --cpu as a differentiator. build:clang_config --cpu=k8 # Use the default Bazel C++ toolchain to build the tools used during the # build. build:clang_config --host_crosstool_top=@bazel_tools//tools/cpp:toolchain
Đối với một mục build:{config_name} --flag=value
, cờ dòng lệnh --config={config_name}
sẽ được liên kết với cờ cụ thể đó. Xem tài liệu về cờ được sử dụng: crosstool_top
, cpu
và host_crosstool_top
.
Khi bạn tạo mục tiêu bằng bazel build --config=clang_config //main:hello-world
, Bazel sẽ sử dụng chuỗi công cụ tuỳ chỉnh từ cc_toolchain_suite
//toolchain:clang_suite
. Bộ công cụ này có thể liệt kê nhiều chuỗi công cụ dành cho từng loại CPU, và đó là lý do bộ công cụ này được phân biệt với cờ --cpu=k8
.
Vì Bazel sử dụng nhiều công cụ nội bộ được viết bằng C++ trong quá trình tạo bản dựng, chẳng hạn như trình bao bọc quy trình, nên chuỗi công cụ C++ mặc định có sẵn đã được chỉ định cho nền tảng lưu trữ. Do đó, những công cụ này được tạo bằng chuỗi công cụ đó thay vì chuỗi công cụ đã tạo trong hướng dẫn này.
Định cấu hình chuỗi công cụ C++
Để định cấu hình chuỗi công cụ C++, hãy liên tục tạo ứng dụng và loại bỏ từng lỗi như mô tả dưới đây.
Chạy bản dựng bằng lệnh sau:
bazel build --config=clang_config //main:hello-world
Vì bạn đã chỉ định
--crosstool_top=//toolchain:clang_suite
trong tệp.bazelrc
nên Bazel sẽ gửi lỗi sau:No such package `toolchain`: BUILD file not found on package path.
Trong thư mục không gian làm việc, hãy tạo thư mục
toolchain
cho gói và một tệpBUILD
trống bên trong thư mụctoolchain
.Chạy lại bản dựng. Vì gói
toolchain
chưa xác định mục tiêuclang_suite
, nên Bazel sẽ gửi lỗi sau:No such target '//toolchain:clang_suite': target 'clang_suite' not declared in package 'toolchain' defined by .../toolchain/BUILD
Trong tệp
toolchain/BUILD
, hãy xác định một nhóm tệp trống như sau:package(default_visibility = ["//visibility:public"]) filegroup(name = "clang_suite")
Chạy lại bản dựng. Bazel gửi lỗi sau:
'//toolchain:clang_suite' does not have mandatory providers: 'ToolchainInfo'
Bazel phát hiện ra rằng cờ
--crosstool_top
trỏ đến một quy tắc không cung cấp trình cung cấpToolchainInfo
cần thiết. Vì vậy, bạn cần trỏ--crosstool_top
đến một quy tắc cung cấpToolchainInfo
– đó là quy tắccc_toolchain_suite
. Trong tệptoolchain/BUILD
, hãy thay thế nhóm tệp trống bằng đoạn mã sau:cc_toolchain_suite( name = "clang_suite", toolchains = { "k8": ":k8_toolchain", }, )
Thuộc tính
toolchains
sẽ tự động liên kết các giá trị--cpu
(và--compiler
khi được chỉ định) vớicc_toolchain
. Bạn chưa xác định bất kỳ mục tiêucc_toolchain
nào và Bazel sẽ sớm phàn nàn về điều đó.Chạy lại bản dựng. Bazel gửi lỗi sau:
Rule '//toolchain:k8_toolchain' does not exist
Bây giờ, bạn cần xác định các mục tiêu
cc_toolchain
cho mỗi giá trị trong thuộc tínhcc_toolchain_suite.toolchains
. Thêm phần sau vào tệptoolchain/BUILD
:filegroup(name = "empty") cc_toolchain( name = "k8_toolchain", toolchain_identifier = "k8-toolchain", toolchain_config = ":k8_toolchain_config", all_files = ":empty", compiler_files = ":empty", dwp_files = ":empty", linker_files = ":empty", objcopy_files = ":empty", strip_files = ":empty", supports_param_files = 0, )
Chạy lại bản dựng. Bazel gửi lỗi sau:
Rule '//toolchain:k8_toolchain_config' does not exist
Tiếp theo, hãy thêm mục tiêu ":k8_toolchain_config" vào tệp
toolchain/BUILD
:filegroup(name = "k8_toolchain_config")
Chạy lại bản dựng. Bazel gửi lỗi sau:
'//toolchain:k8_toolchain_config' does not have mandatory providers: 'CcToolchainConfigInfo'
CcToolchainConfigInfo
là trình cung cấp mà bạn sử dụng để định cấu hình các chuỗi công cụ C++ của mình. Để khắc phục lỗi này, hãy tạo một quy tắc Starlark cung cấpCcToolchainConfigInfo
cho Bazel bằng cách tạo tệptoolchain/cc_toolchain_config.bzl
với nội dung sau:def _impl(ctx): return cc_common.create_cc_toolchain_config_info( ctx = ctx, toolchain_identifier = "k8-toolchain", host_system_name = "local", target_system_name = "local", target_cpu = "k8", target_libc = "unknown", compiler = "clang", abi_version = "unknown", abi_libc_version = "unknown", ) cc_toolchain_config = rule( implementation = _impl, attrs = {}, provides = [CcToolchainConfigInfo], )
cc_common.create_cc_toolchain_config_info()
tạoCcToolchainConfigInfo
của trình cung cấp cần thiết. Để sử dụng quy tắccc_toolchain_config
, hãy thêm câu lệnh tải vàotoolchains/BUILD
:load(":cc_toolchain_config.bzl", "cc_toolchain_config")
Đồng thời thay thế nhóm tệp "k8_toolchain_config" bằng nội dung khai báo về quy tắc
cc_toolchain_config
:cc_toolchain_config(name = "k8_toolchain_config")
Chạy lại bản dựng. Bazel gửi lỗi sau:
.../BUILD:1:1: C++ compilation of rule '//:hello-world' failed (Exit 1) src/main/tools/linux-sandbox-pid1.cc:421: "execvp(toolchain/DUMMY_GCC_TOOL, 0x11f20e0)": No such file or directory Target //:hello-world failed to build`
Tại thời điểm này, Bazel đã có đủ thông tin để thử tạo mã nhưng vẫn chưa biết cần sử dụng công cụ nào để hoàn tất các thao tác xây dựng bắt buộc. Bạn sẽ sửa đổi cách triển khai quy tắc Starlark để cho Bazel biết nên sử dụng công cụ nào. Do đó, bạn cần có hàm khởi tạo tool_path() từ
@bazel_tools//tools/cpp:cc_toolchain_config_lib.bzl
:# toolchain/cc_toolchain_config.bzl: # NEW load("@bazel_tools//tools/cpp:cc_toolchain_config_lib.bzl", "tool_path") def _impl(ctx): tool_paths = [ # NEW tool_path( name = "gcc", path = "/usr/bin/clang", ), tool_path( name = "ld", path = "/usr/bin/ld", ), tool_path( name = "ar", path = "/usr/bin/ar", ), tool_path( name = "cpp", path = "/bin/false", ), tool_path( name = "gcov", path = "/bin/false", ), tool_path( name = "nm", path = "/bin/false", ), tool_path( name = "objdump", path = "/bin/false", ), tool_path( name = "strip", path = "/bin/false", ), ] return cc_common.create_cc_toolchain_config_info( ctx = ctx, toolchain_identifier = "local", host_system_name = "local", target_system_name = "local", target_cpu = "k8", target_libc = "unknown", compiler = "clang", abi_version = "unknown", abi_libc_version = "unknown", tool_paths = tool_paths, # NEW )
Hãy đảm bảo rằng
/usr/bin/clang
và/usr/bin/ld
là đường dẫn chính xác cho hệ thống của bạn.Chạy lại bản dựng. Bazel gửi lỗi sau:
..../BUILD:3:1: undeclared inclusion(s) in rule '//main:hello-world': this rule is missing dependency declarations for the following files included by 'main/hello-world.cc': '/usr/include/c++/9/ctime' '/usr/include/x86_64-linux-gnu/c++/9/bits/c++config.h' '/usr/include/x86_64-linux-gnu/c++/9/bits/os_defines.h' ....
Bazel cần biết vị trí để tìm kiếm các tiêu đề đã đưa vào. Có nhiều cách để giải quyết vấn đề này, chẳng hạn như sử dụng thuộc tính
includes
củacc_binary
. Tuy nhiên, ở đây, vấn đề này được giải ở cấp chuỗi công cụ bằng tham sốcxx_builtin_include_directories
củacc_common.create_cc_toolchain_config_info
. Xin lưu ý rằng nếu bạn đang sử dụng một phiên bảnclang
khác, đường dẫn bao gồm cũng sẽ khác. Những đường dẫn này cũng có thể khác nhau tuỳ thuộc vào việc phân phối.Sửa đổi giá trị trả về trong
toolchain/cc_toolchain_config.bzl
thành như sau:return cc_common.create_cc_toolchain_config_info( ctx = ctx, cxx_builtin_include_directories = [ # NEW "/usr/lib/llvm-9/lib/clang/9.0.1/include", "/usr/include", ], toolchain_identifier = "local", host_system_name = "local", target_system_name = "local", target_cpu = "k8", target_libc = "unknown", compiler = "clang", abi_version = "unknown", abi_libc_version = "unknown", tool_paths = tool_paths, )
Chạy lại lệnh bản dựng, bạn sẽ thấy lỗi như:
/usr/bin/ld: bazel-out/k8-fastbuild/bin/main/_objs/hello-world/hello-world.o: in function `print_localtime()': hello-world.cc:(.text+0x68): undefined reference to `std::cout'
Lý do là vì trình liên kết bị thiếu thư viện chuẩn C++ và không tìm thấy các ký hiệu của thư viện đó. Có nhiều cách để giải quyết vấn đề này, chẳng hạn như sử dụng thuộc tính
linkopts
củacc_binary
. Ở đây, vấn đề này được giải quyết bằng cách đảm bảo rằng mọi mục tiêu sử dụng chuỗi công cụ đều không phải chỉ định cờ này.Sao chép mã sau vào
cc_toolchain_config.bzl
:# NEW load("@bazel_tools//tools/build_defs/cc:action_names.bzl", "ACTION_NAMES") # NEW load( "@bazel_tools//tools/cpp:cc_toolchain_config_lib.bzl", "feature", "flag_group", "flag_set", "tool_path", ) all_link_actions = [ # NEW ACTION_NAMES.cpp_link_executable, ACTION_NAMES.cpp_link_dynamic_library, ACTION_NAMES.cpp_link_nodeps_dynamic_library, ] def _impl(ctx): tool_paths = [ tool_path( name = "gcc", path = "/usr/bin/clang", ), tool_path( name = "ld", path = "/usr/bin/ld", ), tool_path( name = "ar", path = "/bin/false", ), tool_path( name = "cpp", path = "/bin/false", ), tool_path( name = "gcov", path = "/bin/false", ), tool_path( name = "nm", path = "/bin/false", ), tool_path( name = "objdump", path = "/bin/false", ), tool_path( name = "strip", path = "/bin/false", ), ] features = [ # NEW feature( name = "default_linker_flags", enabled = True, flag_sets = [ flag_set( actions = all_link_actions, flag_groups = ([ flag_group( flags = [ "-lstdc++", ], ), ]), ), ], ), ] return cc_common.create_cc_toolchain_config_info( ctx = ctx, features = features, # NEW cxx_builtin_include_directories = [ "/usr/lib/llvm-9/lib/clang/9.0.1/include", "/usr/include", ], toolchain_identifier = "local", host_system_name = "local", target_system_name = "local", target_cpu = "k8", target_libc = "unknown", compiler = "clang", abi_version = "unknown", abi_libc_version = "unknown", tool_paths = tool_paths, ) cc_toolchain_config = rule( implementation = _impl, attrs = {}, provides = [CcToolchainConfigInfo], )
Nếu bạn chạy
bazel build --config=clang_config //main:hello-world
, cuối cùng, mã sẽ được tạo.
Đánh giá bài tập của bạn
Trong hướng dẫn này, bạn đã tìm hiểu cách định cấu hình một chuỗi công cụ C++ cơ bản, nhưng chuỗi công cụ sẽ mạnh mẽ hơn so với ví dụ đơn giản này.
Các điểm cần lưu ý là:
– Bạn cần chỉ định cờ --crosstool_top
trong dòng lệnh sẽ
trỏ đến cc_toolchain_suite
– Bạn có thể tạo lối tắt cho một cấu hình cụ thể bằng cách sử dụng
tệp .bazelrc
– cc_toolchain_suite có thể liệt kê cc_toolchains
cho các CPU và trình biên dịch khác nhau. Bạn có thể sử dụng cờ dòng lệnh như --cpu
để phân biệt.
– Các em phải cho chuỗi công cụ biết vị trí của các công cụ này. Trong hướng dẫn này có một phiên bản đơn giản để bạn truy cập vào các công cụ qua hệ thống. Nếu muốn có một phương pháp độc lập hơn, bạn có thể đọc về không gian làm việc tại đây. Các công cụ của bạn có thể đến từ một không gian làm việc khác và bạn phải cung cấp các tệp đó cho cc_toolchain
với các phần phụ thuộc mục tiêu trên các thuộc tính, chẳng hạn như compiler_files
. Bạn cũng cần thay đổi tool_paths
.
– Các em có thể tạo các tính năng để tuỳ chỉnh những cờ sẽ được chuyển đến các thao tác khác nhau (có thể là liên kết hoặc bất kỳ loại hành động nào khác).
Tài liệu đọc thêm
Để biết thêm thông tin chi tiết, hãy xem phần Cấu hình chuỗi công cụ C++