IMS Open Corpus Workbench (CWB)

Release 3.5 BETA

Installation Guide -- Windows Supplement

This file describes how to build and install the CWB from source code for

Microsoft Windows. You should first read the instructions in the main

INSTALL file, as the Windows procedures are in large part elaborations on

the process for Unix.

For our purposes, Cygwin counts as a Unix environment not a Windows

environment; so if you're building on Cygwin, the notes in this file do

not apply.

GENERAL NOTES

CWB is designed for Unix-like (i.e. POSIX-compatible) operatign systems.

Porting such systems to run on Windows is a non-trivial undertaking.

Fortunately, there exist projects designed to allow programs for Unix to

be built for Windows with minimal porting. CWB's Windows installation

procedure is built on one such system, MinGW ("Minimalist GNU for Windows").

In theory, MinGW can be used to build Unix-like programs for Windows

EITHER within Windows itself, OR by creating the Windows executables

from a Unix-like machine ("cross-compiling"). We currently only provide

instructions for the LATTER of these, i.e. the cross-compilation;

we hope to move over to building natively on Windows in the near future.

For the time being, if you do not have a Unix-like machine from

which to build Windows binaries, your best option is to install Cygwin

and build within Cygwin.

The notes in this section are directed at creating a 32-bit Windows build;

you are welcome to attempt to build targeting Win64 but we do not provide

official instructions yet.

The CWB team has tested cross-compilation using the following Unix OSes:

- Ubuntu

- Debian

Others (Fedora, etc.) may well work, and we welcome reports of problems,

success stories, etc.

The Windows binaries are tested on Windows 7 (currently); we understand

them also to work on Windows 8, 8.1 and 10. Windows XP is no longer a

target platform as of 2016, as Microsoft has end-of-lifed it.

PREREQUISITES

You need all the tools listed in the PREREQUISITES section of the main

INSTALL file. In addition, you need the following:

- the MinGW cross-compiler (an installation of GCC which produces Win32

executables rather than executables for the Unix system it runs on)

- versions of the PCRE and Glib libraries compiled for use with the

cross-compiler

- you DO NOT need cross-compiler versions of GNU Readline or ncurses,

as these libraries are not used in the Windows builds.

The rest of the file discusses these issues in detail.

INSTALLING THE CROSS COMPILER

For cross-compilation, you will need to install the MinGW system,

including the Windows cross-compiler version of GCC.

There are two MinGW projects: the original mingw.org, also known as "mingw32";

and the forked project "Mingw-w64" mingw-w64.org. We have not tested the use

of the latter (although there's no reason why it should not work), so in this

document we assume you will install original-brand MinGW.

On Debian/Ubuntu, this can be done by installing the package "mingw32" together

with two other "mingw32-.*" packages on which it depends.

On Fedora and derived RPM-based Linux variants, the list of packages begining

in "mingw32-" is much longer, but cross-compilation doesn't require all of

them. You need "mingw32-gcc" and all its dependencies.

Alternatively, or on systems that are not package managed, the MinGW

cross-compiler can be downloaded from the MinGW project website:

http://www.mingw.org/wiki/LinuxCrossMinGW

However you install MinGW, make sure the cross-compiler binary file

(usually i586-mingw32msvc-gcc) and the other executables with this prefix

are all available via your path.

FINDING OUT THE CROSS-COMPILER'S "HOME" DIRECTORY

Standard Unix puts development files in various known system locations, i.e.

/usr/lib, /usr/include, and so on. These are for *native* compilation.

The cross-compiler will have its own equivalent sub-directories, under its

own base directory. To progress further, we need to know what that is.

The following shell command should get the cross-compiler to tell you its

base directory:

MINGW_OUTPUT_TMP=`$GCC --print-search-dirs | grep ^install` ; \

echo ${MINGW_OUTPUT_TMP:9}

(in place of "$GCC" in the above insert the actual cross-compiler program;

as noted above, usually i586-mingw32msvc-gcc).

For instance, on some Ubuntu versions, the result of that command is

/usr/lib/gcc/i586-mingw32msvc/4.2.1-sjlj

(the last part of the path varying depending on the version of the

cross-compiler you have installed).

The good news is that if the command above is successful, the CWB "make"

system will be able to add the "home" directory on its own, as it uses

that exact command. If that automatic method doesn't work, you will need

to find out what the directory is by exploring your system, and then insert

the answer manually into your config.mk file. This is explained below.

Either way, you will need to note that directory for use in commands

for installing cross-compiler versions of PCRE and Glib. Later in this

document, the variable $MINGW_CROSS_HOME refers to the path to this

directory (should be a full, absolute path - not a relative path).

PREREQUISITE EXTERNAL LIBRARIES FOR WINDOWS BUILD

When cross-compiling for Windows, you need versions of Glib/PCRE

that have been compiled *to run under Windows*, not the usual *nix versions.

You can either build these, or install pre-built versions; this section is

divided into parts (a/b/c/d) to cover those possibilities for GLib and PCRE.

(a) PCRE -- build-yourself

First, go to www.pcre.org and download the source of the library; make sure

you get the latest available version of the 8.xx series, NOT the 10.xx

series. Once downloaded, decompress the code.

Next, we need to use the MinGW cross-compiler to build the library files;

these then should be placed into the right library directory for the MinGW

cross-compiler to find it. The same applies to the header file. We have

found that PCRE's "make install" will do this for you, *IF* it has been

configured with the right options (if you run the ./configure script without

the right options, it will be compiled for Unix and placed in the normal

gcc places, possibly overwriting what you previously had there, and breaking

your system).

The "right options" for configuring PCRE are something like the following

(assuming that the cross-compiler is i586-mingw32msvc-(gcc|ld|...):

CC=i586-mingw32msvc-gcc CC_FOR_BUILD=$NORMAL_CC ./configure \

--host=i586-mingw32msvc \

--enable-utf8 --enable-unicode-properties --enable-jit \

--enable-newline-is-any --disable-cpp --enable-static \

--prefix=$MINGW_CROSS_HOME \

--exec-prefix=$MINGW_CROSS_HOME \

--oldincludedir=$MINGW_CROSS_HOME/include

.... where $NORMAL_CC is your *normal* compiler, i.e. the one you'd use to

build CWB for your actual system (usually just "gcc");

.... and where $MINGW_CROSS_HOME is the directory within which header

and library files *for the the cross-compiler* live, as noted above. So,

on Ubuntu and with PCRE v8.39, for instance, this adds up to the following:

cd pcre-8.39

CC=i586-mingw32msvc-gcc CC_FOR_BUILD=gcc ./configure \

--host=i586-mingw32msvc \

--enable-utf8 --enable-unicode-properties --enable-jit \

--enable-newline-is-any --disable-cpp --enable-static \

--prefix=/usr/lib/gcc/i586-mingw32msvc/4.2.1-sjlj \

--exec-prefix=/usr/lib/gcc/i586-mingw32msvc/4.2.1-sjlj \

--oldincludedir=/usr/lib/gcc/i586-mingw32msvc/4.2.1-sjlj/include

make

sudo make install

If you don't use PCRE's "make install", but instead move the library/header

files that you have built manually to the cross-compiler's directories,

these are the files you should make sure get copied:

- Library files (in $MINGW_CROSS_HOME/lib):

- libpcre.a

- libpcre.dll.a

- libpcre.la

- libpcreposix.a

- libpcreposix.dll.a

- libpcreposix.la

- Package config files (in $MINGW_CROSS_HOME/lib/pkgconfig):

- libpcre.pc

- libpcreposix.pc

- Header files (in $MINGW_CROSS_HOME/include):

- pcre.h

- pcreposix.h

- Dynamic link libraries (in $MINGW_CROSS_HOME/bin):

- libpcre-1.dll

- libpcreposix-0.dll

- Programs (also in $MINGW_CROSS_HOME/bin)

- pcre-config

- pcregrep.exe

- pcretest.exe

Not all the above are needed for CWB, but it is better to install the

whole library than part of it, for sake of consistency.

As an overall general note, you should make sure to consult the PCRE

documentation on building for cross-compilation. The first place to

check is the README supplied in the PCRE download.

(b) PCRE -- download

Some Linux distros provide versions of PCRE precompiled for use with MinGW.

Fedora, for example, provides the package "mingw32-pcre".

Debian/Ubuntu DO NOT provide any such package, so on such systems it is

necessary to use the build-yourself method above.

Fedora packaging system aside, to our knowledge there are no suitable

places to download pre-built Windows versions of the PCRE library.

The PCRE homepage contains a link to downloadable binaries provided by the

GnuWin32 project, but you SHOULD NOT attempt to use these.

The project is unmaintained and in consequence the PCRE library files

provided are too old to be suitable for use with CWB.

(c) GLIB -- build-yourself

The "build-yourself" procedure for Glib is roughly the same as for PCRE;

the instructions in this section are somewhat abbreviated for that reason.

First, download and decompress a copy of the code from the GTK project

website (www.gtk.org). At time of writing, the source code was available

on the Linux download page (http://www.gtk.org/download/linux.php) but not

the Windows page - so please ignore the latter!

Next, build the library, and move it into the cross-compiler's directories.

Exactly as with PCRE, using the correct configure variables should result

in a makefile which will let you accomplish this simply using "make install".

Before building, you might want to look at the instructions here:

https://developer.gnome.org/glib/stable/glib-building.html

The "right options" for configuring Glib are something like the following

(assuming that the cross-compiler is i586-mingw32msvc-(gcc|ld|...):

CC=i586-mingw32msvc-gcc CC_FOR_BUILD=$NORMAL_CC ./configure \

--host=i586-mingw32msvc \

--prefix=$MINGW_CROSS_HOME \

--exec-prefix=$MINGW_CROSS_HOME \

--oldincludedir=$MINGW_CROSS_HOME/include

.... where $NORMAL_CC is your *normal* compiler, i.e. the one you'd use to

build CWB for your actual system (usually just "gcc");

.... and where $MINGW_CROSS_HOME is as explained above. So, on Ubuntu and

with Glib 2.48.1, for instance, this adds up to the following:

cd glib-2.48.1

CC=i586-mingw32msvc-gcc CC_FOR_BUILD=gcc ./configure \

--host=i586-mingw32msvc \

--prefix=/usr/lib/gcc/i586-mingw32msvc/4.2.1-sjlj \

--exec-prefix=/usr/lib/gcc/i586-mingw32msvc/4.2.1-sjlj \

--oldincludedir=/usr/lib/gcc/i586-mingw32msvc/4.2.1-sjlj/include

make

sudo make install

You may find that you need to install other libraries in order to build

Glib. Unfortunately, this is beyond the scope of this document.

(d) GLIB -- download

Some Linux distros provide versions of PCRE precompiled for use with MinGW.

Fedora, for example, provides the packaeg "mingw32-glib2".

Debian/Ubuntu DO NOT provide any such package, so on such systems it is

necessary to use the build-yourself method above.

The GTK project formerly made available pre-built Windows DLL files for

Glib (along with its other libraries). You may have used these files

previously - earlier versions of this file pointed to a set of files in

.zip format accessible via the GTK website at URL

http://www.gtk.org/download-windows.html .

However, GTK no longer makes the relevant downloads available; it is

therefore necessary to cross-compile Glib unless your Linux distro is

one of the ones that provides a suitable package.

If you can find a downloadable build, then the instructions are as follows.

These are the files you should copy across if you have to install manually.

As with the earlier instructions for PCRE, this is a maximal, "better safe

than sorry" list, to avoid problems based on intra-Glib dependencies; you

might also be able to build CWB having copied a more limited set of files.

- Library files

FROM glib-dev_$version_win32.zip/lib

TO $MINGW_CROSS_HOME/lib

- gio-2.0.lib

- glib-2.0.lib

- gmodule-2.0.lib

- gobject-2.0.lib

- gthread-2.0.lib

- libgio-2.0.dll.a

- libglib-2.0.dll.a

- libgmodule-2.0.dll.a

- libgobject-2.0.dll.a

- libgthread-2.0.dll.a

- Header files

FROM glib-dev_$version_win32.zip/include/glib-2.0

TO $MINGW_CROSS_HOME/include/glib-2.0

- gio/*

- glib/* including glibconfig.h

- gobject/*

- glib-object.h

- glib.h

- gmodule.h

- Dynamic link libraries

FROM glib_$version_win32.zip/bin

TO

- libgio-2.0-0.dll

- libglib-2.0-0.dll

- libgmodule-2.0-0.dll

- libgobject-2.0-0.dll

- libgthread-2.0-0.dll

CONFIGURING CWB

First manually edit config.mk to select "mingw" as the configuration file for the "platform".

Then, if

It is important to note that if you have a *nix system and you have Glib

installed with pkg-config, then the results you get back from pkg-config WILL

NOT WORK for the cross-compiler. pkg-config will always tell you about

the files/directories for the *nix system itself, not the differently-

compiled files you need for the cross-compiler.

For both PCRE and Glib, the cross-compiler needs to know where the header and

library files are. Assuming you have followed the procedure above, they will

be in places the cross-compiler checks anyway. But if not, then you may need

to add extra compiler/linker flags in the config file to inform it about their

location.

The cross-compiler doesn't need to know about the location of the DLLs,

because it doesn't use them. Instead, they are actually copied into the

release file as part of the "make release" command. So the location of

the DLLs needs to be available as part of the makefile system.

You can specify this yourself by adding the appropriate information to

your config.mk file (as explained in the comments to that file). You need to

set either LIB_DLL_PATH (path to a directory containing both PCRE and Glib

DLLs) or both LIBPCRE_DLL_PATH and LIBGLIB_DLL_PATH.

If you are using the auto-build script (./install-scripts/build-win32),

this script will make a "guess" as to the location of the DLLs. So in this

case, there is no need to set LIB(PCRE|GLIB|)_DLL_PATH - but if you do,

whatever you specify will override the "guess".

BUILDING THE WINDOWS RELEASE

With all the above done, you can now move on to actually building.

With the correct changes made to the config.mk file, building the CWB

binaries is the same as on Unix:

make clean

make depend

make all

Running "make install" is meaningless in this case, because of course you will

want to install the binaries on a different machine. To create an archive for

easy transport of the Windows .exe files, together with PDFs of the man files,

run

make release

This will generate a zip file containing the binary release installer, in the

"build" directory. Its name is of the form cwb-$version-windows-i586.zip.

QUICK BUILD SCRIPT

To speed up the steps under the previous heading there is a shell script

which automates the changes to config.mk and the various steps of "making";

run it as follows:

./install-scripts/build-win32

Note, however, that it does not automate the insertion of $MINGW_CROSS_HOME

if that is not guessable via the cross-compiler. See above.

INSTALLING ON THE TARGET MACHINE

To actually install CWB, move the zip file created by the steps above to your

Windows system, and decompress it.

Then run the install-cwb-win batch file. (If it doesn't find the folders it

expects to find, it may ask you some questions.) This script will

- create a folder like C:\Program Files\CWB

- put all the binary files (plus necessary DLLs) in its "bin" subdirectory

- also copy across include/library files (whether or not the latter will

actually work if you try to link against them is untested).

You might also want to

- add the "bin" sub-folder to your PATH environment variable

- move the PDF files from the "man" sub-folder to somewhere more convenient