PW32: Installation

For the first time, you may skip first two sections and proceed to installation instructions. For more general understanding read from the beginning.

• PW32 Directories roadmap
• PW32 Packages
• PW32 Installation
  • User installation
  • Development installation

PW32 Directories roadmap

PW32 is supposed to be POSIX environment, so it uses standard directory structure, following DJGPP in some installation-related details. Generally, PW32 in its entirety installs under single directory, called $PW32_PREFIX. However, it uses some other toplevel directories (such as /etc and /var) for specific needs.

Below, all usual directories used by PW32 are described:

$PW32_PREFIX/

Top-level PW32 directory. Under it, all binaries and 'fixed' (those which aren't supposed to change frequently) data files are stored. As you see, this directory name and position is not fixed. For production system, $PW32_PREFIX should be /usr, but until PW32 reached that level, other value may be used.

$PW32_PREFIX/bin/

Binaries directory. All standard command files (binaries and scripts) are contained here. This also place for dynamically linked libraries (DLLs). This differes from standard *nix practise, when dynamic libraries are kept where static are (in $PW32_PREFIX/lib/). This reflect Win32 idiosyncrasy, where dynamic libraries are more executables, than libraries (for example, object linked not against DLL itself, but instead against auxilary 'import' library). This directory should be on PATH. (Note by the way that having DLLs there also saves one PATH entry).

$PW32_PREFIX/lib/

Libraries directory. This directory contains:

• Static object libraries
• Import libraries for dynamic libraries (see above)
• Other program-specific files, usually under separate subdirectories

This directory NEED NOT be on PATH.

$PW32_PREFIX/include/

Include directory. This directory and its subdirectories contain system C header files. Occasional programs also use this directory for storing includable/library files (though specific dir under $PW32_PREFIX/lib/ is a better location).

$PW32_PREFIX/i386-mingw32msvc/

This directory contains host-specific files for GCC. Since PW32 currently uses mingw32-hosted compiler, it called that way.

$PW32_PREFIX/doc/

Documentation directory. Under subdirectories of this directory packages put their documentation. In some cases, when there's no real documenation, some put short notice directly into doc.

$PW32_PREFIX/man/

Directory for man pages.

$PW32_PREFIX/info/

Directory for GNU info files.

$PW32_PREFIX/manifest/

This is DJGPP's package management directory. Each package puts into this directory two files:

<packagename>.ver

File, first line of which contains short package description, and the rest - more comprehensive description (the latter is probably my extension to DJGPP's conventions).

<packagename>.mft

File which list all files contained in packaged (with relative paths).

I believe there's package manager which supports this simple scheme. But even without it, it's no fuzz to find out to which package particular file belongs, or upgrade specific package.

$PW32_PREFIX/var/build/

Under this directory stored per-package directories with build scripts and patches used to build PW32 packages. Contents of this directory are not required for normal work and whole directory can be safely deleted.

/bin/

Many applications require standard Unix shell available as /bin/sh, so $PW32_PREFIX/bin/sh.exe should be copied there. Other common or occasional expectations are:

• /bin/pwd
• /bin/cat
• /bin/echo

In these cases, symlinks from $PW32_PREFIX/bin/* will be enough.

/etc/

This is site-wide configuration directory. Many packages expect this directory to exist.

/tmp/

Default directory for temporary files. Most programs will use directory pointed by TMPDIR if it is set, but some may still unconditionally use /tmp.

/var/lib/pw32/dll/

This directory contains different builds of PW32 runtime library, pw32.dll. Under it, in directories with name of timestamp (YYYY-MM-DD), specific binary snapshots reside. This scheme is intended for development of PW32, so, in case of problems, previous snapshots can be used. It is not required to adhere to it. In the future, a utility could be written which will allow easily switch among different snapshots.

/var/log/pw32/

PW32's strace facility by default stores log files here.

PW32 Packages

PW32 distribution consists of number of packages (or modules, in SourceForge terms) to faciliate sensible downloads, seamless updates, and generally, usage satisfaction. This section describes PW32-specific packages. Note that package filename usually differs from package name, since it contains version number and/or timestamp, and file suffix. All packages are intented to be installed under $PW32_PREFIX directory, unless noted otherwise.

pw32

This is the source for core PW32 components: runtime library, support utilities, and testsuite. You need this only if you want to build library yourself or develop PW32 (and to preserve your rights for Free Software, of course!).

pw32-core-bin

Prebuilt PW32 core: runtime and link libraries, includes, utilities. You usually want to get this, unless you only need some of the POSIX tools and not going to develop for PW32.

pw32-dll-snapshot

Recent snapshot of pw32.dll, PW32's runtime library. Whenever internal change occurs which doesn't touch headers, startup files, other sensitive components of PW32, only this need to be updated. This package also helpful for people who want to use PW32 on user level. This should be unpacked into /var/lib/pw32/dll/ and copied to $PW32_PREFIX/bin/ from there.

pw32-utils-bin

In the case you decided to get only pw32-dll-snapshot and not pw32-core-bin, you should also pick up this, which contains support utilities.

pw32-buildenv

PW32 building environment, i.e. gcc, binutils and system libraries. Currently this is based on mingw32-hosted tools (courtesy of Mumit Khan) and doesn't need to be updated frequently. Also, note that only C frontend currently included.

pw32-doc

PW32 documentation (site snapshot) for offline browsing.

PW32 Installation

Choosing installation location (i.e. $PW32_PREFIX)

Whatever type of installation you choose - user-type, where only provided utilities are installed and used, or full, where porting and development of POSIX/Unix software is supported, you should decide on your $PW32_PREFIX value (see Directories roadmap for description). Highly recommended value is /usr, all precompiled packages are configured for it. If you will choose other location, you may need to recompile some packages which use compiled-in paths (such packages have prefix directive in their .ver file) Before installing PW32 make sure you have no other package installed under $PW32_PREFIX.

Preparing for PW32 installation

Create $PW32_PREFIX directory.

One problem you may want to pay attention on this stage is the fact that win32 systems includes idiosyncratic MSDOS-rooted utilities having names that clash with POSIX names. At least following are offenders:

• sort.exe
• find.exe
• more.{com,exe}

Setting up environment for PW32

The next step is to setup correct environment for PW32. The easiest way for this is, after installing pw32-core-bin package, rename file $PW32_PREFIX/bin/pw32rc.bat-dist to $PW32_PREFIX/bin/pw32rc.bat and tweak it to your needs. Then, use this file to startup PW32 session or as part of the startup.

What that startup script does, among other things, is setting up value of the PATH environment variable. pw32rc.bat prepends value of $PW32_PREFIX\bin to its contents. It is recommended that your default PATH do not contain references to any other POSIX-like package (DJGPP, CygWin, Mingw). More specifically, you should make sure that they come after PW32 in PATH. You might want to have them on the PATH if PW32 doesn't include software which you require and other packages provide. For example, I currently use info from DJGPP. It lives in /usr/local/bin, listed after /usr/bin in PATH.

For more information on environment variables pertinent to PW32, see environment variables used by PW32. Normally, you should set at least PW32_PREFIX and ROOT_DRV.

Location for pw32.dll

pw32.dll, PW32 runtime library, was originally intended to be placed in $PW32_PREFIX/bin. However, experience showed that it is not the best location for it. Reason for that is the strange design of win32 shared libraries - they are not libraries per se, they are executables (with multiple entry points ;-) ). There're many signs of that, and one pertinent to current case is that dlls are searched on the PATH, where executables are. So, for PW32 applications to be executed, directory with pw32.dll must be on the PATH. However, it's not possible to guarantee that - any POSIX app can set PATH to any value it likes without compunction. And some do, one common example is regression testsuites. So, for robust operation some other location should be used. I hate to give such advise, but Windows' system directory is really best bet for it.

Installing PW32 package

All PW32 software comes bundles in packages, which are archives with uniform content structure and special files which describe that structure and other information. PW32 uses usual zip archives as a packaging format. Also, package conventions was designed in such way that package installing and upgrading may be achieved by mere unpacking package in $PW32_PREFIX directory. However, some packages require additional installation steps. With the lack of package manager (which should be written, of course), you should yourself check for necessity of those steps and perform them manually.

All package meta-information is specified in a single file, located as manifest/<package_name>.var in package archive. You read that file before (and after ;-) ) installation.

Here is short summary of the directives in .ver file you especially should be concerned about:

prefix

Presence of this directives means that package is non-relocatable and should be installed exactly in the directory specified as the value of the directive. For PW32, it is /usr. If your $PW32_PREFIX, you should recompile this package, or you may have problems with running its programs.

requires

This package requires specified package(s) to be already present to work or install. I.e. you must install those packages first.

{pre,post}-install-script

If one of this directive is specified, script pointed by the argument (relative to package root) should be executed before or after package unpacking.

More info on packaging is available in separate document (a must-read).

User installation

You should get binaries of main PW32 components: pw32-dll-snapshot and pw32-utils-bin. Unpack pw32-utils-bin to $PW32_PREFIX. Put pw32.dll from pw32-dll-snapshot to $PW32_PREFIX/bin/ .

Then, just pick utility packages which you need and install them into $PW32_PREFIX. If you'll use bash-bin, copy bash.exe to /bin/sh.exe.

Development installation

Following packages required for being able to compile bare C code for PW32: pw32-core-bin and pw32-buildenv. To use standard GNU configure system, you need to install:

1. The basic triple: fileutils-bin, textutils-bin, sh-utils-bin
2. That will allow you to install bash-bin
3. grep-bin, sed-bin, diffutils-bin to follow.

Installing that will allow you to run most configure scripts. However, to develop/port applications, full install is recommended.