For notes on Installation see this topic

Building the SP consists of downloading and (usually) building the dependencies and then building the Shibboleth components.

This process is entirely performed from the command line using the nmake utility.

Environment

All building is done from within a Visual C command line.  The 64 bit builds for the dependencies should be done from a 64 bit environment and likewise the 32 bit.  

Both architectures (32/64) for the Shibboleth components are built at the same time and this can be done from either a 32 bit or  64 bit command line..

Directory layout

Everything is built under a common directory referred to as the root directory.  The shibboleth products (xmltooling, OpenSAML and the SP) have fixed names (cpp-xmtooling, cpp-opensaml, cpp-sp), and the build is managed from the cpp-msbuild subdirectory.  The names of the dependency directories can be controlled by the environmental variables.

Environmental variables

General Environment
NameDefaultUsed to build...Description
ROOT_DIR<Mandatory>everythingThe location of the build
SEDsedZLIBThe location of the sed command
PERLperlOpenSSLThe location of the perl command
Zlib ENVIRONMENT


NameDefaultUsed to build...Description
ZLIB_DIRzlib-1.2.11

ZLIB, Shib DLLs, Installer

The name of the directory with the xlib sources
ZLIB_IMPLIB
ZLIBThe name of the zlin library (hence zlib1.lib)
ZLIB_MM_VERSION1.2.11InstallersThe version given to the zlib MergeModule
ZLIB_FILE_VERSION1_2_11InstalllersThe garnish added to the DLL(hence zlib1_2_11.dll). Changing this requires changes to versions.props
Log4Shib ENVIRONMENT


NameDefaultUsed to build...Description
LOG4SHIB_DIRcpp-log4shib

Log4Shib, Shib DLLs, Installers

The name of the directory with the log4shib sources.
LOG4SHIB_FILE_VERSION1_0InstallersThe garnish added to the DLL (hence log4shib1_0D.dll). Changing this requires changes to versions.props
LOG4SHIB_MM_VERSION

Installers

The version given to the Log4Shib MergeModule
OpenSLL ENVIRONMENT
NameDefaultUsed to build...Description
OPENSSL_DIRopenssl-1.1.0g

OpenSSL
All Shib DLLs
Installers

The name of the directory with the OpenSSL sources.
OPENSSL_FILE_VERSION1_1InstallersThe garnish added to the OpenSSL DLLs (hence libcrypto-1_1.dll). Changing this requires changes to versions.props
OPENSSL_MM_VERSION

Installers

The version given to the OpenSSL MergeModule
Curl ENVIRONMENT
LIBCURL_DIRlibcurl-7.57.0

Curl, Shib DLLs
Installers

The name of the directory with the Curl sources
LIBCURL_VERSION7.57.0InstallersThe Version of Libcurl (used for paths and Merge Module Version)

Xerces ENVIRONMENT

XERCES_DIRxerces-c-3.2.0

Xerces, Shib DLLs
Installers

The name of the directory with the Santuario sources
XERCES_MM_VERSION3.2.0InstallersThe version of Xerces (used for Merge module version)
XERCES_FILE_VERSION3_2InstallersThe garnish on the DLL name. Hence xerces-3_2.dll. Changing this requires changes to versions.props

XmlSecurity (Santuario) ENVIRONMENT

XSEC_DIRxml-security-cpp

XmlSecurity
all Shib DLLs
Installers

The name of the directory with the Santuario sources
XSEC_MM_VERSION2.0.0InstallersThe version of XML Security (used for Merge module version)
XSEC_FILE_VERSION2_0InstallersThe garnish on the DLL name. Hence xsec_2_0d.dll. Changing this requires changes to versions.props
Apache ENVIRONMENT
NameDefaultUsed to build...Description
APACHE_13_ROOT
not usedLocation of Apache 1.3 build tree as downloaded from ApacheLounge
APACHE_20_ROOT
mod_shib20.soLocation of 32 bit Apache 2.0 build tree as downloaded from ApacheLounge
APACHE_22_ROOT
mod_shib22.soLocation of 32 bit Apache 2.2 build tree as downloaded from ApacheLounge
APACHE_22_ROOT64
mod_shib22.soLocation of 64 bit Apache 2.2 build tree as downloaded from ApacheLounge
APACHE_24_ROOT
mod_shib24.soLocation of 32 bit Apache 2.4 build tree as downloaded from ApacheLounge
APACHE_24_ROOT64
mod_shib24.soLocation of 64 bit Apache 2.4 build tree as downloaded from ApacheLounge


The build takes configuration from environmental variable set up in the file cpp-msbuild/dependencies/config.bat.  The complete list of settings can be found from either build system with the target 'environment',

Obeying the Component rules

The component rules require that if the name of a DLL is changed then the component GUID is changed.  In terms of the Shibboleth build this means that if any of the environmental variables ending in _FILE_VERSION change then you need to edit the Versions.cpp file.  This is because this environmental variable is used to control the name of the DLL during the build of the dependencies and during the build of the installer.

The versions.props file has code to ensure that the installers will not build if a file version is changed without a change to the GUID for instance.  The code contains comments to explain what to do

  <PropertyGroup Label="CurlGuidsBad" Condition="'$(LIBCURL_FILE_VERSION)' != '7_58'">
    <CurlFileVersion>BAD_LIBCURL_FILE_VERSION</CurlFileVersion>
    <!-- Changing LIBCURL_FILE_VERSION version requires changing the GUIDs since it is garnish on the name -->
  </PropertyGroup>

In this case, if LIBCURL was updated to version 7.59 then it would be relevant to change LIBCURL_FILE_VERSION to 7_59. This in turn qould require changing the code section above and the 4 GUIDs associate with libcurl (<LibCurlGuid32>, <LibCurlGuid64>, <LibCurlGuid32d>, <LibCurlGuid64d>).  If you don't understand why read up on the file version and component rules.  Or just do it.

A GUID generator is shipped as part of Visual Studio.  The ones you use need to be in 'registry format'

Downloaded External Dependencies

Apache

Apache should be downloaded (and verified) from Apache Lounge.  

The location of each download should be set up as properties as per the above.

FastCgi

FastCGI is not packaged as part of the V3 SP.

Built External Dependencies

The following external dependencies 

are rebuilt under the control of the makefile dependency.make in the subdirectory dependencies of the cpp-msbuild project.  This make file will build the dependencies specified for the architecture associated with the Visual studio build environment from which it is invoked.  For example

d:\Program Files (x86)\Microsoft Visual Studio\2017\Professional\VC\Auxiliary\Build\vcvars32.bat

or

d:\Program Files (x86)\Microsoft Visual Studio\2017\Professional\VC\Auxiliary\Build\vcvars64.bat

Several of the dependencies are built into common area and then installed into architecture specific directories. It is therefore not safe to build both architectures in parallel.

Preconditions


    "VC-WIN64A" => {
        inherit_from     => [ "VC-WIN64-common", asm("x86_64_asm"),
                              sub { $disabled{shared} ? () : "x86_64_uplink" } ],
        AS               => sub { vc_win64a_info()->{AS} },
        ASFLAGS          => sub { vc_win64a_info()->{ASFLAGS} },
        asoutflag        => sub { vc_win64a_info()->{asoutflag} },
        asflags          => sub { vc_win64a_info()->{asflags} },
        sys_id           => "WIN64A",
        bn_asm_src       => sub { return undef unless @_;
                                  my $r=join(" ",@_); $r=~s|asm/x86_64-gcc|bn_asm|; $r; },
        perlasm_scheme   => "auto",
        multilib         => "_1-x64",
    },



    "VC-WIN64AD" => {
        inherit_from     => [ "VC-WIN64-common", asm("x86_64_asm"),
                              sub { $disabled{shared} ? () : "x86_64_uplink" } ],
        AS               => sub { vc_win64a_info()->{AS} },
        ASFLAGS          => sub { vc_win64a_info()->{ASFLAGS} },
        asoutflag        => sub { vc_win64a_info()->{asoutflag} },
        asflags          => sub { vc_win64a_info()->{asflags} },
        sys_id           => "WIN64A",
        bn_asm_src       => sub { return undef unless @_;
                                  my $r=join(" ",@_); $r=~s|asm/x86_64-gcc|bn_asm|; $r; },
        perlasm_scheme   => "auto",
        multilib         => "_1D-x64",
    },



NMAKE targets

clean

Cleans all build environments

all

Builds all targets

per-dependency targets

Each of the 6 dependencies (openssl, log4shib, zlib, xerces, curl and xmlsec) has four targets associated

In addition 

Building Shibboleth

A centralized makefile cpp-msbuild/build.make allows all the Shibboleth components to be build (cpp-xmltooling, cpp-saml, cpp-sp)

In contrast to the dependency build this nmake files makes both architectures (X64 and ia386)

The final outcome of a build is usually the two installers.

Preconditions

NMAKE targets

Rebuilding individual projects is usually better achieved from within Visual Studio (which also takes configuration from  $(BuildRoot)buildpath.props and $(BuildRoot)cpp-msbuild//versions.props.  

Ensure that the environment is setup before starting Visual Studio

h:\Perforce\VS2017>cpp-msbuild\dependencies\config.bat
h:\Perforce\VS2017>cpp-sp\Projects\vc15\Shibboleth.sln

Windows Subsystem for Linux (WSL)

The SP has been built using WSL (largely to test the Linux build environment without a Linux machine), but this is not supported.  The Linux build instructions should be followed

If for whatever reason you need to use WSL the following helps in the run up to the configure stage.

autoreconf -fvi
autoconf