分岔的 Tomcat Native

netty-tcnative 是 Tomcat Native 的一個分岔版本。它包含了一組由 Twitter, Inc 貢獻的變更，例如：

• 簡化原生程式庫的分發和連結
• 專案的 Maven 化
• 優化 OpenSSL 支援

為了減輕維護負擔，我們為每一個穩定的上游版本建立一個專屬的分支，並在上面套用我們自己的變更，同時將維護的分支數量維持在最少。

netty-tcnative 是多模組專案，並建立了許多成品，能讓它在多種環境中使用。

在版本 2.0.49.Final 中 maven 包裝方式略有變更。這些變更對 Maven 使用者來說很不錯，但對 Gradle 及 Bazel 使用者來說則可能會造成一些麻煩。

• 對於 Gradle，解決方案是明確宣告 tcnative 相依性（具分類器）。
• 對於 Bazel，解決方案是使用包含此修復程式版本的 Bazel 版本：https://github.com/bazelbuild/rules_jvm_external/pull/687

這是最簡單可用的相依性，因為它不需要特定平台的分類器

<project>
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>io.netty</groupId>
      <artifactId>netty-tcnative-boringssl-static</artifactId>
      <version>2.0.0.Final</version>
    </dependency>
    ...
  </dependencies>
  ...
</project>

在應用程式 pom.xml 中，加入 os-maven-plugin 擴充功能及對應於您平台的 netty-tcnative-boringssl-static 相依性

<project>
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>io.netty</groupId>
      <artifactId>netty-tcnative-boringssl-static</artifactId>
      <version>2.0.0.Final</version>
      <classifier>${os.detected.classifier}</classifier>
    </dependency>
    ...
  </dependencies>
  ...
  <build>
    ...
    <extensions>
      <extension>
        <groupId>kr.motd.maven</groupId>
        <artifactId>os-maven-plugin</artifactId>
        <version>1.4.0.Final</version>
      </extension>
    </extensions>
    ...
  </build>
  ...
</project>

當部署到 Maven Central 時，Netty-tcnative 會使用分類器，並針對下列平台提供發行版

在應用程式 pom.xml 中，加入 os-maven-plugin 擴充功能及 netty-tcnative 相依性

<project>
  <properties>
    <!-- Configure the os-maven-plugin extension to expand the classifier on -->
    <!-- Fedora-"like" systems. -->
     <os.detection.classifierWithLikes>fedora</os.detection.classifierWithLikes>
  </properties>
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>io.netty</groupId>
      <artifactId>netty-tcnative</artifactId>
      <version>2.0.0.Final</version>
      <classifier>${os.detected.classifier}</classifier>
    </dependency>
    ...
  </dependencies>
  ...
  <build>
    ...
    <extensions>
      <extension>
        <groupId>kr.motd.maven</groupId>
        <artifactId>os-maven-plugin</artifactId>
        <version>1.4.0.Final</version>
      </extension>
    </extensions>
    ...
  </build>
  ...
</project>

Netty-tcnative 在部署至 Maven Central 時使用分類器為各種平台提供版本。在 Linux 上，請注意 OpenSSL 對 Fedora 派生版和其它 Linux 版本使用不同的 soname。從 1.1.33.Fork7 開始，我們透過為 Linux 部署兩個獨立版本（請參閱下表）因應這種限制。

使用 classifierWithLikes 會將 os-maven-plugin 設定為變更已產生的 os.detected.classifier 屬性。如果您的建置包含依賴於 os.detected.classifier 的其它相依性，您可以使用 antrun 外掛程式手動建立 netty-tcnative 分類器

<project>
  <dependencies>
    <dependency>
      <groupId>io.netty</groupId>
      <artifactId>netty-tcnative</artifactId>
      <version>2.0.0.Final</version>
      <classifier>${tcnative.classifier}</classifier>
    </dependency>
  </dependencies>

  <build>
    <extensions>
      <!-- Use os-maven-plugin to initialize the "os.detected" properties -->
      <extension>
        <groupId>kr.motd.maven</groupId>
        <artifactId>os-maven-plugin</artifactId>
        <version>1.4.0.Final</version>
      </extension>
    </extensions>
    <plugins>
      <!-- Use Ant to configure the appropriate "tcnative.classifier" property -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-antrun-plugin</artifactId>
        <executions>
          <execution>
            <phase>initialize</phase>
            <configuration>
              <exportAntProperties>true</exportAntProperties>
              <target>
                <condition property="tcnative.classifier"
                           value="${os.detected.classifier}-fedora"
                           else="${os.detected.classifier}">
                  <isset property="os.detected.release.fedora"/>
                </condition>
              </target>
            </configuration>
            <goals>
              <goal>run</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

要使用以 OpenSSL 為基礎的 SSLEngine 實作，請使用 io.netty.handler.ssl.SslContext 類別

public static void main(String[] args) throws Exception {
  File certificate = new File("certificate");
  File privateKey = new File("privateKey");
  SslContext sslContext =
    SslContextBuilder.forServer(certificate, privateKey)
                     .sslProvider(SslProvider.OPENSSL)
                     .build();
  ...
}

public class MyChannelInitializer extends ChannelInitializer<SocketChannel> {

  private final SslContext sslCtx;
  
  public MyChannelInitializer(SslContext sslCtx) {
    this.sslCtx = sslCtx;
  }
  
  @Override
  public void initChannel(SocketChannel ch) throws Exception {
    ChannelPipeline p = ch.pipeline();
    if (sslCtx != null) {
      p.addLast(sslCtx.newHandler(ch.alloc()));
    }
    ...
  }
}

Netty 會將 netty-tcnative-XXX 製件所提供的共用函式庫解壓縮至暫存目錄，然後使用 java.lang.System.load(String) 載入它。

請注意，netty-tcnative 製件中的共用函式庫會動態連結至 Apache Portable Runtime (APR) 和 OpenSSL。它們必須存在於函式庫載入路徑中，例如系統目錄、$LD_LIBRARY_PATH 和 %PATH%。

• 如果您使用 Linux，您可能無需執行任何動作，因為您可以使用系統的套件管理員安裝它。
• 如果您使用 Mac，您必須使用 Homebrew 安裝 openssl 套件。
• 如果您使用 Windows，您必須
  • 自行建置 APR，
  • 安裝 Windows 的 OpenSSL，以及
  • 將包含 .DLL 檔案的目錄新增至 %PATH%。

重要提示：如果您使用 Linux 並想要使用 ALPN（http2 需要此功能），您需要確保您已安裝 openssl >= 1.0.2。如果您的發行版的套件系統未提供這個功能，您需要自行編譯並設定 LD_LIBRARY_PATH，如 如何建置 中所述。

如果在 Fedora 30 或更新版本上，請執行 dnf -y install libxcrypt-compat 來安裝必要的相依性。

如果您未執行此操作，您極有可能性會看見類似於：「libcrypt.so.1：無法開啟共用物件檔案：找不到此類檔案或目錄」的錯誤訊息

您通常不需要自行建置 netty-tcnative，因為我們會官方提供已與原生函式庫結合的 JAR，適用於 Linux x86_64、Mac OS X x86_64 和 Windows x86_64。如果您正在尋找 SNAPSHOT 建置，請瀏覽 Sonatype Snapshots。

如果您使用的是我們尚未提供已結合原生函式庫的 JAR 之平台，例如 Windows x86_32，請參閱本節中的指示。

建置本機相依性時，必須驗證第三方相依性的完整性。而且建置時相依性更新將引發檢查碼驗證失敗，而套件維護人員應遵循下列程序，以確保套件完整性後才能更新檢查碼以比對。

• 從 http://ftp.gnu.org/gnu/autoconf/autoconf-X.Y.Z.tar.gz 下載 tgz 和 tgz.sig
• gpg --keyserver keys.gnupg.net --recv-keys 2527436A
• gpg --verify autoconf-X.Y.Z.tar.gz.sig

• 從 https://apr.apache.org/download.cgi 下載
• 安全取得 apr 的 MD5 摘要: apache 網站連結到 http，但須修改為 https
• 貼上摘要到檔案中
• 驗證摘要 md5 -r apr-X.Y.Z.tar.gz | cut -d " " -f 1 | diff -u apr-X.Y.Z.tar.gz.md5 -

• 簽署公開金鑰: RWQg/nutTVqCUVUw8OhyHt9n51IC8mdQRd1b93dOyVrwtIXmMI+dtGFe
• (可從 https://www.openbsd.org/libressl/signing.html 下載公開金鑰)
• 從 http://ftp.openbsd.org/pub/OpenBSD/LibreSSL/ 下載 tarball、簽章和 SHA256.sig
• 使用從 https://www.openbsd.org/libressl/signing.html 下載的 libressl.pub 驗證: signify -C -x SHA256.sig -p /path/to/libressl.pub libressl-X.Y.Z.tar.gz

• 從 https://www.openssl.org/source/ 下載 tarball 和 SHA256 簽章
• 驗證摘要 sha1sum openssl-X.Y.Z.tar.gz | cut -d " " -f 1 | diff -u openssl-X.Y.Z.tar.gz.sha256 -

boringssl 目前並未針對 tcnative 建置以密閉方式進行版本控管: 它只會在建置時間從 上游 Google Git repo 的 chromium-stable 分支中擷取

建置套件並安裝到本機 Maven 儲存庫

git clone https://github.com/netty/netty-tcnative.git
cd netty-tcnative
# To build a specific version: (e.g. netty-tcnative-2.0.0.Final)
git checkout netty-tcnative-[version]
# To build a snapshot: (e.g. 2.0.0.Final)
git checkout [branch]
./mvnw clean install

如需在 IBM Z (s390x) 上為 Linux 建置 netty-tcnative 函式庫，請遵循此處提供的說明，並將其安裝到您的本機 Maven 儲存庫。

首先，您需要安裝 Xcode。然後，記得也要安裝 command line 工具

xcode-select --install

複製 netty-tcnative 儲存庫，然後使用 Homebrew 安裝所需套件

git clone https://github.com/netty/netty-tcnative.git
cd netty-tcnative
brew bundle

建置套件並安裝到本機 Maven 儲存庫

# To build a specific version: (e.g. netty-tcnative-2.0.0.Final)
git checkout netty-tcnative-[version]
# To build a snapshot: (e.g. 2.0.0.Final)
git checkout [branch]
./mvnw clean install

此區段說明如何在 64 位元 Windows 中建置。建置 32 位元系統時，可能必須調整其中一些步驟。

安裝下列套件

• Visual C++ 2013 Express
• Windows 10 SDK
• CMake
  • 安裝過程中，選取 Add CMake to the system PATH for current user
• Perl
• Ninja
  • 將執行檔解壓縮到 C:\Workspaces\，然後將 C:\Workspaces 加入 PATH
• Go
• Yasm
  • 下載到 C:\Workspaces
  • 設定環境變數 ASM_NASM=C:\Workspaces\yasm-1.3.0-win64.exe.
• OpenSSL.
  • 安裝過程中，選取 Copy OpenSSL DLLs to: The OpenSSL binaries (/bin) directory
  • 設定下列環境變數
    • OPENSSL_INCLUDE_DIR=C:\OpenSSL-Win64\include
    • OPENSSL_LIB_DIR=C:\OpenSSL-Win64\lib
• Apache Portable Runtime (APR) 1.5.2
  • 解壓縮到：C:\Workspaces\apr-1.5.2
  • 從 C:\Workspaces\apr-1.5.2 的命令提示字元 (cmd.exe) 中執行下列命令
    • "C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat" x86_amd64
    • nmake /f Makefile.win ARCH="x64 Release" PREFIX=..\apr-1.5.2-dist buildall install
    • xcopy include\arch\win32\*.h ..\apr-1.5.2-dist\include /d
    • xcopy include\arch\*.h ..\apr-1.5.2-dist /d
  • 設定下列環境變數
    • APR_INCLUDE_DIR=C:\Workspaces\apr-1.5.2-dist\include
    • APR_LIB_DIR=C:\Workspaces\apr-1.5.2-dist\lib

現在，啟動命令提示字元 (cmd.exe) 並載入 Visual C++ 所需的環境變數

"C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat" x86_amd64

複製 netty-tcnative 並建置

git clone https://github.com/netty/netty-tcnative.git
cd netty-tcnative
REM To build a specific version: (e.g. netty-tcnative-2.0.0.Final)
git checkout netty-tcnative-[version]
REM To build a snapshot: (e.g. 2.0.0.Final)
git checkout [branch]
mvnw clean install

簽出 bootstrap 分支並透過上游 tcnative 版本執行 new-fork 指令碼，此動作會帶您至一個新的、已完全 maven 化的分支，其名稱與上游 tcnative 版本相同。例如

$ git checkout bootstrap
$ ./new-fork 1.1.29 1

將建立一個稱為 1.1.29 的新分支，其中包含 tcnative-1.1.29 的 maven 化分支。請注意，此分支不包含任何會變更 tcnative 主程式碼的修補程式。您可能想要從已修補的其他分支中挑選一些提交。