打造爵士樂

本指南假設您已建立要建構的模糊測試器。並使用與該指南相同的範例程式碼。

Fuchsia 使用 GN (中繼建構系統) 產生 .ninja 檔案，明確說明如何建構系統。GN 目標是建構圖中的節點，代表特定輸出內容，例如程式庫或可執行檔。GN 範本是產生其他目標的規則。

為了盡可能簡化新增模糊測試器的程序，Fuchsia 提供與模糊測試相關的 GN 範本。

如要為 Fuchsia 的模糊測試器二進位檔建立建構規則，請參閱適用語言的「Fuchsia 程式庫模糊測試器 GN 範本」。
如要為開發主機的模糊測試器二進位檔建立建構規則，請參閱主機程式庫模糊測試器 GN 範本
如要為模糊測試器元件建立建構規則，請參閱「Fuchsia 模糊測試器元件 GN 範本」。
如要為模糊測試器二進位檔套件建立建構規則，請參閱 Fuchsia 模糊測試器套件 GN 範本。

定義建構規則後，即可使用 fx 建構模糊測試器。

Fuchsia 程式庫模糊測試器 GN 範本

每種語言都有特定的 Fuzzer GN 範本：

C/C++

fuchsia_library_fuzzer GN 範本會產生 executable 目標，編譯並連結模糊測試目標函式與待測試程式碼和模糊測試引擎。

如要為 C 或 C++ 模糊測試器建立建構規則，請將 fuchsia_library_fuzzer GN 目標新增至適當的 BUILD.gn，例如具有對應單元測試規則的目標。

例如：

import("//build/fuzz.gni")

fuchsia_library_fuzzer("parser-fuzzer") {
  sources = [ "parser_fuzzer.cc" ]
  deps = [ ":parser-lib" ]
}

荒漠油廠

rustc_fuzzer GN 範本會產生 GN 目標，將 Rust 模糊測試目標函式編譯為 C 物件檔案，然後與模糊測試引擎連結。

如要為 Rust 模糊測試器建立建構規則，請將 rustc_fuzzer GN 目標新增至 Crate 的 BUILD.gn。

選擇新增這項指定目標的位置和方式時，請考量下列事項：

建議模糊測試器名稱與模糊測試目標函式名稱相符，並在 Rust 程式庫 (即 src/lib.rs) 中加入模糊測試目標函式。按照這些建議操作時，您可以將範本主體留空。舉例來說，使用toy_example_arbitrary 範例時，您會在 BUILD.gn 中新增下列項目：

import("//build/rust/rustc_fuzzer.gni")

rustc_fuzzer("toy_example_arbitrary") {
}

如果模糊測試目標函式名稱與模糊測試器名稱不同，您必須使用 rustfunction 參數提供該名稱。舉例來說，使用toy_example_u8 範例時，您會在 BUILD.gn 中新增下列項目：

import("//build/rust/rustc_fuzzer.gni")

rustc_fuzzer("toy_example_raw_bytes") {
    rustfunction = "toy_example_u8"
}

如果無法輕鬆將要測試的程式碼分解為程式庫，則可使用 Rust 二進位檔，並執行兩個額外步驟：
您必須從編譯中排除 main 函式，以及模糊測試時未使用的任何項目，例如僅在 main 中使用的匯入項目。例如：
```
#[cfg(not(fuzz))]
use only::used::in::main;

#[cfg(not(fuzz))]
fn main() { ... }
```
您必須使用 source_root 參數，明確向 rustc_fuzzer 提供模糊測試目標函式。舉例來說，在 BUILD.gn 中：
```
import("//build/rust/rustc_fuzzer.gni")

rustc_fuzzer("toy_example_with_main") {
    source_root = "src/main.rs"
}
```

選取模糊測試變體時，這些範本會將 [libFuzzer] 編譯器執行階段與提供的 sources、deps 或兩者連結，藉此建構模糊測試器二進位檔。這段程式碼必須提供模糊測試目標函式。

否則，系統會透過將測試架構與提供的程式碼連結，建構模糊測試單元測試。這項測試架構會使用固定輸入內容 (例如長度為零的輸入內容) 呼叫模糊測試目標函式。這項測試可確保模糊測試器能夠編譯及連結，即使不是為了模糊測試而建構也一樣。

主機程式庫模糊測試器 GN 範本

您也可以使用 Fuchsia 建構系統，在開發主機上建構執行模糊測試器。如要建構主機模糊測試器，請使用 host_library_fuzzer GN 範本。

例如：

host_library_fuzzer("my_host_fuzzer") {
  sources = [ ... ]
  deps = [ ... ]
}

您可以使用 fx 建構主機模糊測試器，不必將其新增至 Fuchsia 元件或套件。

Fuchsia Fuzzer 元件 GN 範本

fuchsia_fuzzer_component 範本會建立用於執行模糊測試器的元件。可包含一般元件參數，例如 component_name 和 deps。

例如：

fuchsia_fuzzer_component("my-fuzzer-component") {
  component_name = "my-fuzzer"
  manifest = "meta/my-fuzzer.cml"
  deps = [ ":my-corpus"]
}

程式庫模糊測試工具的資訊清單必須包含 libfuzzer 的預設分片。模糊測試器的輸出名稱必須以套件相對路徑的形式，做為第一個程式引數提供。其他引數可能包括 libFuzzer 選項，或種子輸入目錄的套件相對路徑，也就是所謂的種子語料庫。

例如：

{
    include: [
        "//sdk/lib/inspect/client.shard.cml",
        "//src/sys/fuzzing/libfuzzer/default.shard.cml",
        "//src/sys/test_runners/fuzz/default.shard.cml",
        "//src/sys/test_runners/tmp_storage.shard.cml",
        "syslog/client.shard.cml",
    ]
    program: {
        args: [
            "test/my-fuzzer",
            "-max_input_size=256",
            "data/my-corpus",
        ]
    }
}

種子語料庫應與元件 deps 中包含的 resource 目標相符。

例如：


import("//build/dist/resource.gni")

resource("my-corpus") {
  sources = [
    "input0",
    "input1",
    "input2",
  ]
  outputs = [ "data/my-corpus/{{source_file_part}}" ]
}

Fuchsia 模糊測試器套件 GN 範本

fuchsia_fuzzer_package範本會將模糊測試器元件綁定至 Fuchsia fuchsia_test_package，與綁定測試元件的方式類似。建構 fuchsia_fuzzer_package 範本時，系統會新增特定建構規則，在模糊測試工具鍊變體建構模糊測試器時進行註解，藉此區分範本。

範本包含依語言整理的模糊測試器元件清單參數。每種語言都有一組工具鍊提供的支援清除器，做為編譯器執行階段。如果所選工具鍊變體包含特定語言支援的清除器，對應的模糊測試器元件清單就能執行模糊測試。

舉例來說，如果 C++ 工具鍊支援假設的 examplesan，但 Rust 工具鍊不支援，且選取了 examplesan-fuzzer 變數，則下列套件定義只會建構 my-cpp-fuzzer 進行模糊測試，以及 my-rust-fuzzer 進行測試。

fuchsia_fuzzer_package("my-fuzzers") {
  cpp_fuzzer_components = [ ":my-cpp-fuzzer" ]
  rust_fuzzer_components = [ ":my-rust-fuzzer" ]
}

如果套件沒有以相應語言編寫的模糊測試器，就不必加入清單。

fuchsia_fuzzer_package 可以使用與 fuchsia_package 相同的所有參數。

例如：

fuchsia_fuzzer_package("my-fuzzers") {
  package_name = "the-fuzzers"
  cpp_fuzzer_components = [ ":my-fuzzer" ]
}

定義完成後，套件必須納入建構依附元件圖表，就像任何其他測試套件一樣。通常是指將其加入一組測試。

例如：

group("tests") {
  deps = [
    ":my-test-package",
    ":my-fuzzers",
  ]
}

使用 `fx` 建構模糊測試器

如上所述，只有明確告知 Fuchsia 建構系統要使用適當的模糊測試變體，對模糊測試器進行模糊測試，系統才會建構模糊測試器。這些是已知變體，結尾為 -fuzzer。每個變體都是 sanitizer 變體的擴充功能，包括：

asan：使用 AddressSanitizer 偵測記憶體錯誤，例如在釋放或傳回記憶體後使用記憶體、溢位堆積和堆疊緩衝區溢位等。
ubsan：使用 UndefinedBehaviorSanitizer 偵測違反語言規格的行為，例如有符號的整數溢位、指標對齊錯誤和更多。

如要使用模糊測試變體建構 fuzzer_package，最簡單的方法就是搭配 fx set 使用 --fuzz-with <sanitizer> 旗標。

例如：

fx set core.x64 --fuzz-with asan --with //bundles/tests --include-clippy=false
fx build

執行 fx set 後，您可以使用 ffx fuzz list 查看目前設定的模糊測試器。您可以使用其他 ffx fuzz 指令執行模糊測試器。