How to build PHENIX on Windows

Contents

Introduction

This document describes how to build Phenix from sources on Windows 7 or more recent versions. Given that Windows does not have all the necessary tools for building Phenix, how to set up these tools is covered here in some detail.

A typical PHENIX installation takes up the order of 5Gb disk space. If you build PHENIX from scratch including an installer this will be of the order of 15Gb. Throughout this document the "command prompt" (archaichally termed the "DOS prompt" by some) refers to the commandline interpreter program, cmd.exe, which serves the same purpose as bash or tcsh on Unix. On the Startup menu it is located in the "Accessories" group.

Necessary tweaks of the Windows PC

Automatically run script for every command prompt

On Unix a startup script such as .bashrc or .tcshrc are convenient for initiating commonly used environment variables for a user. Windows has a different technique for achieving the same for the command prompt. In the registry editor, regedit.exe, locate the AutoRun registry key:

HKEY_CURRENT_USER\Software\Microsoft\Command Processor\AutoRun

If there is no AutoRun key present under the "Command Processor" key then create a new one of type string. The value of this key can be set to the full path of a cmd script you have written that does something such as defining environment variables for that command prompt. This script can have any name but we will call it ntshell.cmd and store it in path pointed to by the %HOMEDRIVE%%HOMEPATH% environment variables.

Warning

Entering wrong values in the registry or accidentally deleting values may render Windows bricked. Always ensure you have a recent "System Restore" point in your Windows backup. This will allow you to boot Windows to "Last known good configuration" if the registry gets corrupted.

Alternatively one can also define environment variables through the Control Panel\All Control Panel Items\User Accounts and click on "Change my enviroment variables". But this method is not feasible if there are many variables or some variable values are deduced on the fly from scripts. This is the case when initialising environment variables for the compiler.

Run a script once at every logon

Say you have a script in the directory pointed to by the %HOMEDRIVE%%HOMEPATH% environment variables named logon.cmd or whatever. To make this script run once every time you log on to your account, open the Task Scheduler in the "Administrative tools" group in Control Panel, click "Create Task", set "Triggers" to "At logon" and set "Action" to the full path of the logon.cmd file. This script will then run next time you log on.

Necessary prerequisites

To build PHENIX from scratch and create a binary Windows installer the following tools are required:

  • Python 2.7 (any version)
  • makensis from Nullsoft
  • Microsoft Visual C++ 9.0 / Microsoft Visual Studio 2008
  • TortoiseSVN with command line tools
  • TortoiseGit (optionally)
  • Git
  • mtee.exe (optionally for duplicating stdout to file and console)

To build PHENIX from an existing installation with sources the following is required:

  • Microsoft Visual C++ 9.0 / Microsoft Visual Studio 2008

Visual C++ 9.0

If you have not purchased Microsoft Visual Studio 2008 the compiler is available for free in the Windows 7 SDK from the Microsoft website: https://www.microsoft.com/en-gb/download/details.aspx?id=3138&fa43d42b-25b5-4a42-fe9b-1634f450f5ee=True . It should be titled "Microsoft Windows SDK for Windows 7 and .NET Framework 3.5 SP1". Rather than doing the automated installation from the website it may be convenient to download the DVD iso image of the SDK and then do the installation from that. The 32 bit version is named GRMSDK_EN_DVD.iso whereas the 64 bit version is named GRMSDKX_EN_DVD.iso. There are newer versions of this SDK for Windows 7. But as these use more recent C-runtime libraries compiled programs may not be binary compatible with Python 2.7 which is compiled with Visual C++ 9.0. You would still be able to build individual statically linked executables with those newer compilers. But whether or not compiled python modules can run without crashing using a newer runtime is questionable. After installing the compiler it can be invoked once environment variables have been set by calling scripts such as vcvars32.bat or vcvars64.bat from a command prompt or in a build script prior to compiling. These files live in the folder

C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin

OpenSSH tools

The OpenSSH tools used for the Windows build are the ones that come with Git for Windows. If Git has been installed in

C:\Program Files\Git

then OpenSSH tools live in the directory

C:\Program Files\Git\usr\bin

which you must add to the %PATH% environment variable. To have the build run without interrupts the private keys matching your public keys on the remote svn or git repositories must be loaded prior to the build with ssh-agent. Create a .ssh directory in the directory pointed to by the %USERPROFILE% environment variable and store your private keys there. Then add the lines

call "C:\Program Files\Git\cmd\start-ssh-agent.cmd"
SETX SSH_AUTH_SOCK "%SSH_AUTH_SOCK%"
SETX SSH_AGENT_PID "%SSH_AGENT_PID%"

to your logon.cmd file. When you log on it will pick up the private keys in your %USERPROFILE%\.ssh folder. If keys require password you will be prompted for them when you logon to the PC. If a key, say mykey_rsa, is not picked up it can be loaded explicitly by adding the line

ssh-add mykey_rsa

just below the above 3 lines.

Makensis

Makensis from Nullsoft is only required for creating an executable Windows installer package for deployment of PHENIX. Bundled up zip files of an installation is always created.

Bundling base components together as zip files

The Windows build does not need to compile Python or the HDF5 library from scratch. Instead these two components are bundled as separate zip files which bootstrap.py will download from http://cci.lbl.gov/cctbx_dependencies during the first stages of the build. The Python bundle has had all the necessary 3rd party modules added to it for running PHENIX on a PC. Click here for details on how these bundles were created or on how to update this Python bundle with additional modules.

Manual build

From an existing PHENIX installation

If you want to build PHENIX from an existing installation on Windows where the sources have also been installed then do the following:

  1. From the Start menu open a PHENIX Command Prompt.
  2. Run vcvars32.bat or vcvars64.bat depending on the platform.
  3. Change directory to %PHENIX%\build.
    • If compiling for the first time delete all files and directories except config_modules.cmd.
  4. Run config_modules.cmd.
  5. Run libtbx.scons -j <nproc>.

From bootstrap.py

Below is a cmd script for manually building PHENIX with bootstrap.py. It first downloads sources from external repositories, then compiles them, then runs tests and finally creates a binary installer. It is assumed the script is started with command line arguments specifying platform and version label that will be tagged to the executables during the build. Because the PHENIX build will access repositories that requires authentication you must provide appropriate user names for the flags --sfuser= and --cciuser=.

PhenixBuild.cmd

SET PLATFORM=%1
SET PHENIXVERSION=%2

IF DEFINED PLATFORM (
IF %PLATFORM% == x32 (
  call "C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\vcvars32.bat"
  set PYTHONEXE=C:\Python27_32\python.exe
)

IF %PLATFORM% == x64 (
  call "C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\vcvars64.bat"
  set PYTHONEXE=C:\Python27_64\python.exe
)
)

REM Get latest bootstrap.py from Githup
curl https://raw.githubusercontent.com/cctbx/cctbx_project/master/libtbx/auto_build/bootstrap.py > bootstrap.py 2>&1 | mtee build.log
IF ERRORLEVEL 1 (
  EXIT
)

REM             hot update base build
%PYTHONEXE% bootstrap.py --builder=phenix --sfuser=oeffner --cciuser=rdo20 --nproc=10 2>&1 | mtee ..\build%PHENIXVERSION%-%PLATFORM%.log
IF ERRORLEVEL 1 (
  EXIT
)


REM            run tests
%PYTHONEXE% bootstrap.py --builder=phenix --sfuser=oeffner --cciuser=rdo20 --nproc=10 tests 2>&1 | mtee ..\tests%PHENIXVERSION%-%PLATFORM%.log
IF ERRORLEVEL 1 (
  EXIT
)

REM            create installer
call build\bin\libtbx.create_installer.bat --binary --version %PHENIXVERSION% --install_script modules\phenix\phenix\installer\phenix_installer.py ^
 --license modules\phenix\LICENSE.txt --readme modules\phenix\CHANGES --readme modules\phenix\phenix\installer\README --readme modules\phenix\phenix\installer\SOURCES ^
 --dist_dir dist\%PHENIXVERSION% tmp\phenix-installer-%PHENIXVERSION%-win7vc90 2>&1 | mtee ..\CreateInstaller%PHENIXVERSION%-%PLATFORM%.log

In the above script mtee.exe from https://ritchielawrence.github.io/mtee/ is used for piping stdout to a file as well as to the console. It works similar to tee on Unix platforms. A newer version has been compiled that also retains the error code of the program that streams to stdout. This is useful when checking for the success of the builds. Source code and executable is available from http://oeffner.net/development/Stuff/mtee.zip.

Automated build with Buildbot

Assuming the PC runs as a Buildbot slave builds are automated from the Buildbot master machine. Required private keys should be loaded in a logon.cmd script with ssh-agent and command prompts must set the compiler environment variables through an ntshell.cmd script as detailed above.

Issue defining environment variables for the compiler

If you want to run manual builds the environment variables are readily invoked by calling vcvars32.bat or vcvars64.bat. But if doing an automated build with Buildbot all the necessary prerequisites must be acessible in the executable path from a command prompt. At first glance one might add the full path of vcvars32.bat or vcvars64.bat to ntshell.cmd. However, due to a bug in those files this may lead all command prompts to hang in an infinite loop. A workaround is to copy vcvars32.bat and vcvars64.bat to the %HOMEDRIVE%%HOMEPATH% folder and rename them myvcvars32.bat and myvcvars64.bat, respectively. Then replace the lines:

:GetWindowsSdkDirHelper
@for /F "tokens=1,2*" %%i in ('reg query "%1\SOFTWARE\Microsoft\Microsoft SDKs\Windows" /v "CurrentInstallFolder"') DO (
  if "%%i"=="CurrentInstallFolder" (
    SET "WindowsSdkDir=%%k"
  )
)

with

:GetWindowsSdkDirHelper
SET fname=%TEMP%\tmpSDKvars.txt
reg query "%1\SOFTWARE\Microsoft\Microsoft SDKs\Windows" /v "CurrentInstallFolder" > %fname%

@SET WindowsSdkDir=
@for /F "tokens=1,2*" %%i in (%fname%) DO (
  if "%%i"=="CurrentInstallFolder" (
    SET "WindowsSdkDir=%%k"
  )
)
del %fname%

then add a line to your ntshell.cmd with the full path of myvcvars32.bat or myvcvars64.bat like:

call "C:\Users\builder\myvcvars32.bat"

Setting up a PC as a Buildbot slave

The Buildbot slave is installed as per online documentation. For instance for installing a slave named intel-windows-x86_64 in C:\Users\builder\slave chdir to python installed in C:\Python2.7.9x64 type:

C:\Python2.7.9x64\Scripts\easy_install.exe buildbot-slave

and then:

C:\Python2.7.9x64\Scripts\buildslave create-slave C:\Users\builder\slave cci-vm-6.lbl.gov:9989 intel-windows-x86_64 pass

which will make it listen to a master on port 9989 from cci-vm-6.lbl.gov. It is possible to start this slave automatically as a Windows service (equivalent of a Unix daemon) but a simpler procedure is to add the following line:

START "Running BuildBot Slave. Do not close!" /MIN cmd /c C:\Python2.7.9x64\Scripts\buildslave start C:\Users\builder\slave

to your logon.cmd script. Once you have logged on this will place an icon of a minimised command prompt on the taskbar which must not be interfered with, let alone closed. The account can now be locked (Windows key + L) and is ready for doing regular builds from a Buildbot master.

Creating an executable Windows installer program

If the build is done manually from bootstrap.py a Setup.exe program can optionally be created with the last line in the PhenixBuild.cmd script above. If the build is done with Buildbot this installer will currently be created after the various tests have completed. Click here for further details.

Important tweaks for shortening duration of builds

Clear virtual memory at shutdown: Go to Control Panel\All Control Panel Items\Administrative Tools->Local Security Policy->Local Policies->Security Options->Shutdown: Clear virtual memory pagefile

Adjust for best performance of background processes: Check Control Panel\All Control Panel Items\System->Advanced system settings->System Properties | Advanced tab->Performance settings->Performance Options | Advanced tab->Adjust for best performance of Background services

Ensure at least weekly disk defragmentation which does not coincide with doing builds.

If used for nightly builds then disable automatic installation of updates as this often triggers an automatic reboot of the PC. This can be done from the control panel on Windows 7. On Windows 10 follow the steps described on http://www.howtogeek.com/224471/how-to-prevent-windows-10-from-automatically-downloading-updates/

For the directory where nightly builds are done:

  • Exclude it from Windows indexing.
  • Exclude it from on-access virus scan (both read and write)
  • Avoid storing several previous builds since NTFS doesn't perform well when zillions of files are present on the same disc. Zip up previous builds into single files or move them to a different partition if they have to be retained.

Failure to follow these steps could over time make successive builds very slow (+24 hours)