Bilder

# Preparing a Windows machine for Bilder (64-bit only)

For building on Windows 10 in Ubuntu, follow the Linux Bilder setup instructions. 

_Warning:_ In following the directions below, pre-defined env variables like CL, PETSC_DIR, PETSC_ARCH, and others will cause problems.  For example, one user had CL=/nologo which prevented the version and other info from being printed and caused bilder to fail.

# Basic Windows Configuration

## UAC

User Account Control Settings can be fine-tuned (see Control-Panel -> System and Security -> Change User Account Control settings). Set Control Setting to the lowest setting (never notify) to avoid unwanted dialog boxes. This requires a reboot to take effect! The UAC Settings must be adjusted to "never notify" (this action is needed to make symbolic links during bilder runs and building Atlas). 

## File Name too long

This can be a problem when cloning Trilinos.  To fix, see https://www.techinpost.com/the-file-name-too-long/.  In essence, use regedit to go to

```

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem

```

where you can set LongPathsEnabled to 1, then reboot.

## Editing your system path on Windows

Open Run (Windows Key + R), then type *SystemPropertiesAdvanced* and press Enter. 

On the bottom third of the resulting dialog, click the Environment Variables button. 

In System Variables, highlight Path and click Edit. This is where you make changes to your system path.

## If your machine is on a Windows Domain (as compared to a WORKGROUP), then ensure that Windows knows its domainname

If your machine is on a Windows Domain, then Bilder can set a common variable that makes sense in that Domain. If you are not on a Windows Domain, then Bilder will still work fine (except for maybe emailing). To ensure Windows knows its domainname to the following.

* From a command prompt, type the command: 

~~~~~~

ipconfig /all

~~~~~~

Look for the value of the "Primary Dns Suffix" field, which should be your domain name (i.e. txcorp.com).

* If cygwin is already installed,

~~~~~~

ipconfig /all | grep -i "Primary Dns Suffix" | sed -e 's/^.*: //'

~~~~~~

should return the domainname. 

* For Windows 10 machines that are not a member of the Windows Domain, Active Directory, do the following:

    1. Right click on My Computer, select properties

    2. Click on Advanced system settings

    3. Select the computer name tab

    4. Click the change button

    5. Click the more button

    6. Enter the Primary DNS suffix. i.e. txcorp.com 

## Create initial directories

* Create the folder C:\\bin (if not already present).

* Add or move C:\\bin to the front of your system path.

# Software "Required" for Bilder

What is absolutely required for Bilder depends on what you are trying to build. For example, if you are **only building user documentation**, then you only need

* Blat (for emailing yourself)

* Cygwin (for bash shell)

* CMake from an installer

* NASM from an installer

* Python from an installer

* Latex (MikTek below)

* Visual Studio Express (for nmake)

If you have installed a package, you will need to open a new Cygwin window to update PATH in order for your Cygwin bash shell to find the package.  To check whether a package is in PATH, from a Cygwin shell, enter

~~~~~~~~~~~

echo $PATH

~~~~~~~~~~~

After installing the requirements, you can add the arguments,  -W python,cmake, and your installed Python and CMake will be used if your path is correct.

Since bilder uses the C++17 conformance flags, we require:

* Visual Studio 2017 version 15.7 or higher (As of Oct 2019 the latest upgrade version is 15.9.17, which is fine)

* Windows 10 or Windows 10 SDK

Below is a list of the Tools and Libraries that are most often needed.

# Tools (Required for most common builds within Bilder)

## Blat

* Blat is a sendmail client for Windows needed to send emails.*

* Download Blat from [The Blat SourceForge](http://sourceforge.net/projects/blat) Site and extract all files. The latest version should be fine.

* Extract the zip file (e.g. blat3222_32.full.zip) into C:\\bin.

* Copy the contents of the "full" directory up two diretories into "C:\bin" (i.e. C:\bin\blat3222\full\blat.{exe,dll} to C:\bin\blat.{exe,dll}).

* Execute the following command in a cygwin terminal to check that it works

~~~~~~

    blat -install <mail server hostname> <username>@txcorp.com

~~~~~~

## CMake

* CMake is a cross-platform build system needed to configure many of necessary packages.*

* Install [CMake](http://www.cmake.org/files/).

  * Version 3.27 is what we use as of Feb 2024. However, picking a later version is better because it will allow bilder to build future versions of cmake.

  * Add the CMake path to the front of the system path! (Needed to build newer 64 bit versions through Bilder)

  * When this step is complete, make sure the newest CMake is the only one in your system path.

## CYGWIN

*Cygwin is a Unix shell program for Windows and is needed to run the bash code of Bilder.*

### Installing Cygwin

* Download the cygwin installer from [here](http://cygwin.com/install.html)

* From a Windows Elevated Command Prompt, change into the directory that has the recently downloaded setup-x86_64.exe from cygwin, then execute the script below to install cygwin

~~~~~~~

setup-x86_64.exe  ^

--only-site ^

--site https://mirrors.kernel.org/sourceware/cygwin ^

--local-package-dir C:\cygwin64pkgs ^

--root C:\cygwin64 ^

--verbose ^

--prune-install ^

--quiet-mode ^

--packages ^

_autorebase,base-cygwin,base-files,bc,bison,curl,diffutils,dos2unix,emacs,emacs-w32,emacs-X11,flex,gcc-fortran,gcc-g++,gdb,^

git,hostname,make,mercurial,mintty,ncurses,openssh,patch,perl,procps-ng,rebase,subversion,^

tar,time,util-linux,vim,vim-common,vim-doc,vim-minimal,wget,xinit

~~~~~~~~

## Cygwin Post Installation (To be done from a cygwin terminal)

* Create the directory winsame at the top level of both the Cygwin and Windows file systems. You must always work in this directory.  This is critical for getting the ATLAS linear algebra libraries to build. Do this via:

~~~~~~

mkdir /cygdrive/c/winsame

mkdir /winsame

mount C:/winsame /winsame

~~~~~~

To make this permanent, put the following in /etc/fstab. This second entry allows one to construct a valid path with no parentheses as needed for ATLAS.

~~~~~~

C:/winsame /winsame ntfs binary 0 0

C:/Program\040Files\040(x86) /ProgramFilesX86 ntfs binary 0 0

~~~~~~

* Edit /etc/nsswitch.conf by adding the following entry to tell cygwin where to put home directories. e.g

~~~~~~

db_home:  /winsame/%U

~~~~~~

* If 'which link' returns /usr/bin/link, then move this aside (mv /usr/bin/link.exe /usr/bin/linkoff.exe) so that it is not picked up to replace the Visual Studio link.  (This is where we could define BILDER_LINK.)

* Make sure that 'which find' returns the cygwin version (/usr/bin/find), not the Windows version.

* Close the cygwin terminal and open a new one

## Dependencies Tool

*Dependencies* is a tool that shows the DLL's that an executable depends on and is needed to find and copy-in DLLs to a final distribution.

Download [Dependencies](https://lucasg.github.io/Dependencies/) and copy Dependencies*, ClrPhlib.{dll,pdb} into C:\\bin.

(NDesk.Option.dll not needed.)

## JOM

* JOM is an nmake wrapper needed to give  the -j flag capability of Unix make for faster compilation.*

* Create the folder C:\bin (if not already present).

* Add C:\bin to your system path (if not already there).

* Download jom.zip from [the Qt Project](https://wiki.qt.io/Jom).

* Extract the contents of jom.zip

* Move/copy jom.exe to C:\bin (you then can delete the remainder of the contents or keep for historical reasons).

## Ninja Build System (https://ninja-build.org)

* Download  ninja-win.zip from [ninja-win.zip](https://github.com/ninja-build/ninja/releases/tag/v1.12.1)

* Extract ninja from ninja-win.zip and copy into C:\bin

## LaTeX

*LaTeX is a typesetting tool needed for building PDF files for user documentation.*

* Install [Doxygen](http://www.doxygen.nl/).  Choose "Letter" for paper size and "Yes" for "Install missing packages on-the-fly".

* Install Basic MikTeX from [MikTeX](http://miktex.org/). Use the MikTeX Package Manager to install the packages noted at

[[LaTeX packages needed by Bilder]]

* Install [ghostscript](https://www.ghostscript.com/download/gsdnld.html).

## LLVM (Clang)

### Installing LLVM-Clang from a binary installer (easiest way)

Download the Windows (64-bit) installer from http://releases.llvm.org/download.html, and proceed with the installation.

When installing, namespace the installation directory with the major version.  Eg, change LLVM to LLVM17 when asked.

## MPI

*MPI is a message passing interface for parallel code that is needed for some computation engines.*

Download Microsoft MPI v9.0.1 from:

https://www.microsoft.com/en-us/download/details.aspx?id=56727

The binaries (e.g., mpiexec) are obtained by installing msmpisetup.exe.

The libraries (msmpi.lib) are obtained by installing msmpisdk.msi.

The installers will put mpiexec in your path and define the environment variables,

MSMPI_INC

MSMPI_BIN

MSMPI_LIB32

MSMPI_LIB64

which are used by CMake, e.g., to find the needed components of MSMPI.

## NASM (required to build OpenSSL, therefore CMake)

* Download and install from https://nasm.us/

* Make sure this appropriate modifications to your path are made

## Perl (required to build OpenSSL, therefore CMake)

*Perl is a programming language needed by some packages such as Qt*

* Download and install [ActiveState Perl](http://www.activestate.com/activeperl/downloads).

## Python

* Python is built or installed by Bilder.

## RCEDIT

* RCEDIT is a program that allows one to change the icon of an executable after its creation.  It can be obtained from https://github.com/electron/rcedit/releases, and it should be installed in C:\bin.

## Ruby (required to build Qt5)

* Ruby, http://rubyinstaller.org/, must be installed first.

## Subversion

* Subversion is a revision control tool needed by bilder, for example, to know when packages are out of date.*

* Install [TortoiseSVN](https://tortoisesvn.net/downloads.html) with its command line tools.

* With this, you will have two versions of svn on your machine. One is in `/usr/bin` under cygwin, and it is used for direct invocation at the bash command-line. The other is in `\Program Files`, and it is needed for getting repo versions when Bilder is invoked through Jenkins.  As of this writing, 1.9 is recommended (1.8 will also work, but lower versions will not).

~~~~~~

$ where svn

C:\cygwin64\bin\svn.exe

C:\PROGRAM FILES\TORTOISESVN\bin\svn.exe

$ /usr/bin/svn --version | head -1

svn, version 1.9.7 (r1800392)

$ /cygdrive/c/Program\ Files/TortoiseSVN/bin/svn --version | head -n 1

svn, version 1.9.7 (r1800392)

~~~~~~

## Visual Studio

* Visual Studio contains the Microsoft command-line compiler (cl) used by packages with C/C++ code.* 

* Bilder uses VS2022 (MACHINE_FILE=${MACHINE_FILE:-"cygwin.llvm17_vs2022"}) by default.

* Visual Studio should not be in the system path. (Bilder adds this as needed.)

### CUDA

* Bilder currently uses CUDA-11.8 by default, if is can find it.

~~~~~~

BILDER_CUDA_FIND_VERSIONS=${BILDER_CUDA_FIND_VERSIONS:-"11.8 11.7 11.6 11.5 11.2 11.1 11.0 10.2 10.1"}

~~~~~~

# WSL on Windows 10 1909 or newer 

* From within an Administrator enable Powershell window, run the following

```

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

```

* Reboot the computer after running the above two commands from within Powershell

* Update Kernel for WSL2 by downloading and installing https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi

* Run the following command from within an Administrator enabled Powershell window to set the default WSL version to 2.

```

wsl --set-default-version 2

```

* Go to Microsoft store, search for preferred Linux distro, download and install per on screen instructions.

# Libraries (Required for most builds with Bilder)

## OpenSSL

*OpenSSL is a security library needed by Python to build the SSL module, by cmake, libssh, and by Qt.*

*We no longer install OpenSSL on Windows, as Bilder builds it to be consistent with the compiler in use."

### Legacy instructions.

* Download from http://slproweb.com/products/Win32OpenSSL.html

* Choose the Win64 OpenSSL v1.0.2n  (not Light) on 64bit or the Win32 OpenSSL v1.0.2n on 32bit windows.

* **The 1.1 series DOES NOT WORK with either libssh or Qt.**

* You may have to install Visual C++ Redistributables if the installer complains.

* During the installation, select "Copy OpenSSL DLLs to: The OpenSSL binaries (/bin) directory"

* After the installation on 64bit windows, goto C:\Windows\System32 and prepend libssl32.dll, libeay32.dll, and ssleay32.dll with an "OFF", if these files exist.  This and the next step are required so that dependency walker finds the SSL libs from the OpenSSL distro instead of the ones in C:\Windows\System32.

* Add C:\OpenSSL-Win64 (in some cases, we have seen that C:\OpenSSL-Win64\bin should be added instead) or the directory where you installed OpenSSL to the beginning of the system path. In particular, it needs to be in front of the CollabNet path and the Intel client path, because both contain libeay32.dll. A which for the libeay32.dll should give this installed version. For example:

~~~~~~

which libeay32.dll

/cygdrive/c/OpenSSL-Win64/bin/libeay32.dll

~~~~~~

* If built software has unexplained crashes, recheck the above command results.

# Composer-related Libraries (only needed for building ComposerToolkit, can be skipped for documentation builds)

## Git LFS

*Git LFS is a git extension for repos with large files - needed to use git for VisIt repos*

Download and run the installer: https://git-lfs.github.com/

You can adjust the configuration by running (from Cygwin) `git lfs install --force --skip-smudge` with new configuration options.

To ensure that git will find git lfs, add a symbolic link from git's exec path to the location of the git-lfs executable.

~~~~~~

LINK_TO_PATH=`which git-lfs.exe`

LINK_FROM_PATH=`git --exec-path`

cd $LINK_FROM_PATH

ln -s "$LINK_TO_PATH" git-lfs.exe

~~~~~~

## Qt

*Qt is a cross-platform GUI library needed to build packages that have Qt-based user interfaces.*

Qt5 is the recommended version (the previous version, Qt4, instructions are also here too until Qt5 is solid).

### Installing Qt5

These instructions are how to install the pre-built version of Qt 5 (version 5.14.2).  You can skip creating the Qt account.

* Get Qt-5.14.2 from https://download.qt.io/archive/qt/5.14/5.14.2/qt-opensource-windows-x86-5.14.2.exe

* Run this program, selecting `<DRIVE>\winsame\winqt\5.14.2` as your installation directory, where DRIVE is the drive you have winsame on (e.g. D: or C:). (Bilder will find Qt5 if it is here)

* Expand the Qt 5.14.2 section and select the following components:

  * MSVC 2017 64-bit

  * UWP x64 (MSVC 2017)

  * Sources

  * Qt WebEngine

* Optionally, under Developer and Designer Tools, select:

  * Qt Creator 4.11.1 CDB Debugger Support

  * Qt Creator 4.11.1 is selected by default

* Accept all remaining defaults unless otherwise preferred

### Building and Installing Qt4

* Make sure no other Qt is in your system path.

* Get the Qt Libraries from http://download.qt.io/archive/qt/4.8/4.8.7/. Download qt-opensource-windows-x86-vs2010-4.8.7.exe. (The vs2010 in the name is irrelevant as we will build Qt using the source code in this download.)

* Run this program, selecting C:\winsame\builds-XX\winqt\4.8.7 as your installation directory, where XX is the machines file suffix you use (e.g. vs2017).

* If 4.8.7, patch Qt by opening a Cygwin window:

~~~~~~

cd /winsame/builds-vs12/winqt/4.8.7

~~~~~~

To build with VS2017, you may need to patch.  For this you will need python with the patch module installed, which you can obtain by running composerall, e.g., with target, python.  Then do

~~~~~~

/path/to/bilder/installed/python -m patch /path/to/bilder/patches/02-fix_build_with_msvc2015-45e8f4ee.diff

~~~~~~

#### Compiling Qt4

* The copy/paste-able commands below assume VS12.

In a Visual Studio x64 DOS window:

~~~~~~

set VER=2017

REM could be 12

set DRIVE=C:

REM or D:, if you're building there

set SFX=vs%VER%

REM or whatever machine suffix you will be building for, if using a combined compiler build

set QTVER=4.8.7

set INSTALL_DIR=%DRIVE%\winsame\builds-%SFX%\winqt\%QTVER%\%QTVER%\msvc%VER%_64

~~~~~~

Modify the last line as needed, e.g., different drive or subdir.

Set the platform args according to your compiler.

For VS2013 (VS12).

~~~~~~

set PLATFORM_ARGS=-platform win32-msvc2013

~~~~~~

For VS2015 or VS2017:

~~~~~~

set PLATFORM_ARGS=-platform win32-msvc2015

~~~~~~

Then

~~~~~~

%DRIVE%

cd %DRIVE%\winsame\builds-%SFX%\winqt\%QTVER%

configure.exe -prefix %INSTALL_DIR% -debug-and-release -opensource -confirm-license -fast -no-sql-db2 -no-sql-ibase -no-sql-mysql -no-sql-oci -no-sql-odbc -no-sql-psql -no-sql-sqlite -no-sql-sqlite2 -no-sql-tds -no-libtiff -webkit -declarative %PLATFORM_ARGS%

~~~~~~

In a bash window launched from the previous DOS window (try `C:\cygwin64\bin\mintty -`, note that the dash is important!), execute the following (changing vsver to your version)

~~~~~~

export VER=12 # or 2017

export SFX=vs${VER}

cd /winsame/builds-${SFX}/winqt/4.8.7

export INSTALL_DIR=/winsame/builds-${SFX}/winqt/4.8.7/4.8.7/msvc${VER}_64

mkdir -p ${INSTALL_DIR}

cp -R mkspecs ${INSTALL_DIR}

~~~~~~

Back in the Visual Studio x64 DOS window

~~~~~~

%DRIVE%

cd %DRIVE%\winsame\builds-%SFX%\winqt\4.8.7 

set PATH=%PATH%;%DRIVE%\winsame\builds-%SFX%\winqt\4.8.7\bin

nmake

REM Took 3.5 hours on a 2.3 GHz Core2 Duo with Solid State Drive

nmake install

REM Took 10 minutes on a 2.3 GHZ Core2 Duo with Solid State Drive

~~~~~~

* For CMake to find Qt, add INSTALL_DIR to your supra search path when configuring.

* If you want to use this qt outside of Bilder, add ${INSTALL_DIR}/bin to the system path variable.  This may not work if you have more than one Bilder run.

# Additional Useful Tools

## Notepad++

* (Optional) Notepad++ is a free source code editor that is a great tool for Windows.

* Download from http://notepad-plus-plus.org/

* Install and pin to your taskbar.

## Java

Java is needed for setting up the machine to be a Jenkins Slave.

* Download from https://www.java.com/en/download/  (Version 8 Update 181 has a Release date of July 17, 2018) 

* May get a message about the Java Plugin and Chrome. This does not affect the Jenkins slave service.

* Download the JNLP page from the Jenkins server site (link button with label "Launch agent from browser").

* Start a command prompt running as Administrator, then change to the Download directory and type "javaws slave-agent.jnlp" 

* Choose File -> "Install as a service" and follow the dialog messages.

# Experimental Tools and Libraries

These tools have not been fully vetted or built, so you need not do these.

## MinGW

See [[Installing MinGW]].

## ATLAS

See [[Installing ATLAS on Windows]].

## OpenBLAS

See [[Installing OpenBlas on Windows]]

# Cygwin and Paths

(This section assumes the user is familiar with the relations between Cygwin and Windows paths.)

The path is critical for when there are conflicting executables.  This is the case for Subversion and OpenSSL.

The cygwin and Windows versions of svn are incompatible due to line endings, so care must be taken as to which is used at what time.

The path to cygwin's version of svn will be ahead of the Windows Subversion so as to allow users to checkout a project using /usr/bin/svn and never worry about the Windows version of svn.

The path to the installed OpenSSL needs to be in front of the path to Subversion because during the copying in of OpenSSL libraries depends needs to find the ones in the OpenSSL installation not the Subversion installation.

## Usage under Jenkins

Jenkins uses `svnkit`, which is compatible with the Windows version of Subversion of the same version number.  So for jenkins usage, one must have the same version of `svn` installed across all slaves, and when `Bilder` runs under Jenkins, it must be sure to use the Windows version of `svn`.  There are two methods for doing this.  First, `bilder/jenkins/jenkinsbild` defines the environment variables, `BILDER_SVN`, `BILDER_SVNDIR`, and `BLDR_SVNVERSION`, which hold the correct executables to be used by `Bilder`.  However, in the configuration of some packages, notably VisIT in `visit.sh`, the path is used to find `svn`, and this gives the wrong executable.  For these cases, the path is modified just before configuration.

## Summary

* Bilder moves `/usr/bin` to just after the Python path and therefore to before

  `/cygdrive/c/Windows/system32`.

* Put the Windows Subversion path behind the Python path (and so behind `/usr/bin`).

    - `/usr/bin` must be removed from the path when configuring some packages in order to get the correct subversion when building under Jenkins.

# Bilder machine files for cygwin

The Bilder machine file for cygwin and Visual Studio 2013 (VS12) is bilder/machines/cygwin.vs12. It is sourced by bilder using the -m option. It augments PATH and sets the values of the INCLUDE, LIB, and LIBPATH variables.

In case of problems, one should check that the values of these were set correctly. This is done by starting up the **Visual Studio Command Prompt**, then starting rxvt as noted above. The values for or additions to these variables should agree with how they are being set or modified by the cygwin machine files.

# Setup for making Installers

## Visual Studios Redistributables

Download vcredist_x64.exe (Visual C++ Redistributable Packages for Visual Studio 2013)

http://www.microsoft.com/en-gb/download/details.aspx?id=40784

Choose only vcredist_x64.exe executable from list. This should put vcomp120.dll in C:\Windows\System32\

## Sign Tools

* The Microsoft Signtool comes with Visual Studio, however, one must install a code-signing certificate. This process is site-specific so please see your system administrator.

* Contrary to what signtool says, the capicom dll must be copied from C:\Program Files\Microsoft SDKs\Windows\v6.0A\bin to C:\Windows\System32 and must be registered by typing the following at a Command Prompt run as Administrator: 

~~~~~~

cd C:\Windows\System32

REGSVR32 capicom.dll

~~~~~~

## NSIS

NSIS is a scriptable installer maker.

* Install NSIS from [NSIS Download Site](http://nsis.sourceforge.net/Download).

  * For building CMake 64bit and if you are building the composers, you will need a generator for installer executables, which is NSIS (Nullsoft Scriptable Install System) a professional open source system to create Windows installers.

  * Version 2.46 is available as of Aug 21, 2011.

* Add `C:\Program Files (x86)\NSIS\Bin` to your system path.

* Install NSIS Access Control Plugin from [Access Control Plugin Site](http://nsis.sourceforge.net/AccessControl_plug-in).

Copies directories and files into the NSIS installation as follows:

~~~~~~

AccessControl.zip\Contrib\AccessControl --> NSIS\Contrib\AccessControl

AccessControl.zip\Docs\AccessControl --> NSIS\Docs\AccessControl

AccessControl.zip\Plugins\AccessControl.dll --> NSIS\Plugins\x86-ansi\AccessControl.dll

AccessControl.zip\Unicode\Plugins\AccessControl.dll --> NSIS\Plugins\x86-unicode\AccessControl.dll

~~~~~~

# Path

The resulting Windows PATH should look like this...

![](windowsPath.png)

# Notes For Development

[[Notes on debugging Windows executables]]

[[Notes on deleting directories and files owned by other users]]

[[Notes on enabling and disabling the Windows Firewall from the command line]]