native/BUILDING

================================================================================
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
================================================================================

Linux / Unix / OSX (dynamic linking)
====================================

1. Prerequisites

   Install OpenSSL version 3.0.0 or higher
   Install APR version 1.7.0 or higher.
   C compiler (e.g. GCC, clang, etc.), autoconf and/or automake
   Download and expand the source package or use an git checkout

   > cd native

2. Configure build environment

   Note: This step is only required if you are building from an git checkout. It
         is not required when building from a source package.

   >  sh buildconf --with-apr=apr_source_location.

3. Build

   >  configure --with-apr=apr_install_location --with-ssl=openssl_install_location
   >  make

   This should produce a file named libtcnative-2.so


Linux / Unix / OSX (static linking)
===================================

1. Build static version of OpenSSL 3.0.0 or later

   > ./Configure --prefix=~/natives/openssl enable-fips
   > make
   > make install

2. Build static version of APR 1.7.0 or later

   > ./configure --prefix=~/natives/apr
   > make
   > make install

   Note: APR builds both static and dynamic libraries by default.

3. Ensure the static APR library is used

   Edit the ~/natives/apr/lib/libapr-1.la file and comment or delete the
   following sections: dlname='...' and library_names='...'
   This is needed so that libtool picks the static version of the library.

4. Build tc-native

   > ./configure --with-apr=~/natives/apr --with-ssl=~/natives/openssl --prefix=~/natives/tomcat
   > make
   > make install


Windows
=======

1. Prerequisites

  Currently supported Windows OS (release builds use a Windows 2022 VM running
    on VMware)
  Currently support JDK installed (release builds use Temurin 21.0.9)
  git (if you wish to build from source)
  Perl - see OpenSSL build instructions for Windows (release builds use
    Strawberry Perl 5.42.0.1)
  NASM - see OpenSSL build instructions for Windows (release builds use 2.16.01
    included in Strawberry Perl 5.42.0.1)
  Microsoft Visual C compiler (release builds use Visual Studio 2022 17.14.23)

2. Obtain tc-native source

   Download and expand the source package or use an git checkout

3. Build APR

   Unpack the APR source distribution into native\srclib\apr

   > "c:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars32.bat"
   > nmake -f NMAKEmakefile CPU=X86 APR_DECLARE_STATIC=1
 
   > "c:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars64.bat"
   > nmake -f NMAKEmakefile CPU=X64 APR_DECLARE_STATIC=1

4. Build OpenSSL

   > cd ..\openssl

   Unpack the OpenSSL 3.5.x source distribution in this directory

   > "c:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars32.bat"
   > perl Configure no-shared VC-WIN32
   > nmake
   > mkdir out32-x86
   > copy libssl.lib out32-x86\
   > copy libcrypto.lib out32-x86\
   > copy ossl_static.pdb out32-x86\
   > copy apps\openssl.exe out32-x86\
 
   > nmake clean

   > "c:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars64.bat"
   > perl Configure no-shared VC-WIN64A
   > nmake
   > mkdir out32-x64
   > copy libssl.lib out32-x64\
   > copy libcrypto.lib out32-x64\
   > copy ossl_static.pdb out32-x64\
   > copy apps\openssl.exe out32-x64\

5. Copy APR and OpenSSL to versioned directories

   Keeping the various libraries in versioned directories saves having to
   rebuild them next time if the version remains unchanged.    

   > cd ..
   > set OPENSSL_VER=3.5.4
   > set APR_VER=1.7.6
 
   > mkdir \deps-x86\apr-%APR_VER%\include
   > mkdir \deps-x86\apr-%APR_VER%\lib
   > mkdir \deps-x86\openssl-%OPENSSL_VER%\include
   > mkdir \deps-x86\openssl-%OPENSSL_VER%\lib
   > xcopy /E \deps-x86\apr-%APR_VER% \deps-x64\apr-%APR_VER%\
   > xcopy /E \deps-x86\openssl-%OPENSSL_VER% \deps-x64\openssl-%OPENSSL_VER%\
 
   > xcopy /E apr\include \deps-x86\apr-%APR_VER%\include\
   > xcopy /E apr\include \deps-x64\apr-%APR_VER%\include\
 
   > copy apr\WIN7_X86_LIB_RELEASE\apr-1.lib \deps-x86\apr-%APR_VER%\lib
   > copy apr\WIN7_X64_LIB_RELEASE\apr-1.lib \deps-x64\apr-%APR_VER%\lib
   
   > xcopy /E openssl\include\openssl \deps-x86\openssl-%OPENSSL_VER%\include\openssl\
   > xcopy /E openssl\include\openssl \deps-x64\openssl-%OPENSSL_VER%\include\openssl\
   > copy openssl\out32-x86\*.lib \deps-x86\openssl-%OPENSSL_VER%\lib\
   > copy openssl\out32-x64\*.lib \deps-x64\openssl-%OPENSSL_VER%\lib\
   > copy openssl\out32-x86\*.pdb \deps-x86\openssl-%OPENSSL_VER%\lib\
   > copy openssl\out32-x64\*.pdb \deps-x64\openssl-%OPENSSL_VER%\lib\
   > copy openssl\out32-x86\openssl.exe \deps-x86\openssl-%OPENSSL_VER%\
   > copy openssl\out32-x64\openssl.exe \deps-x64\openssl-%OPENSSL_VER%\

 
 6. Build Tomcat Native
 
   > cd ..
   >set JAVA_HOME=C:\java\21.0.9-tem

   > "c:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars32.bat"
   > nmake -f NMAKEMakefile WITH_APR=C:\deps-x86\apr-%APR_VER% WITH_OPENSSL=C:\deps-x86\openssl-%OPENSSL_VER% CPU=X86 APR_DECLARE_STATIC=1 STATIC_CRT=Hybrid
 
   > "c:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars64.bat"
   > nmake -f NMAKEMakefile WITH_APR=C:\deps-x64\apr-%APR_VER% WITH_OPENSSL=C:\deps-x64\openssl-%OPENSSL_VER% CPU=X64 APR_DECLARE_STATIC=1 STATIC_CRT=Hybrid
 
   Tomcat Native Connector DLLs may then be found in native\WIN7_*_DLL_RELEASE


FIPS
====

No additional build steps are required. Configure OpenSSL to use the FIPS
certified provider as the default provider as described in the OpenSSL
documentation:

  https://www.openssl.org/docs/man3.0/man7/fips_module.html