gnubuilds Files

* README_EN.txt
* 2013.02.03
* build_scripts_base

1. DESCRIPTION
2. LICENSE
3. PROJECT TERMS
4. BUILD SCRIPTS DIRECTORY TREE
5. INSTALLATION
5.1. Backends installation
5.1.1. Cygwin
5.1.2. Msys
5.1.3. Msysdvlpr
5.1.4. Mingw
5.2. Build system installation
5.2.1. Build scripts base package
5.2.2. Build scripts project package
5.2.3. Original sources package
5.2.4. Original sources patch package
6. USAGE
6.1. Config directory
6.2. Run a build
6.2.1. Standalone build
6.2.2. Integration build
6.3. Run the build
7. AFTER THE BUILD
8. Additional files
8.1 *.reg files
9. KNOWN ISSUES
9.1. Message about a command or a file that is not found.
9.2. Patch stage blames that one or more patches were already applied, or
     couldn't apply because of error(s) about patch reversing
9.3. Build script ignores to build one or more stages because already built them
9.4. Sometimes the compile.sh script execution hangs after the ctrl-c press
9.5. The "<GnuBuildsRoot>/Temp" directory sometimes is not empty
9.6. The output package doesn't work and/or prints that it did not found
     something in the "/usr/local/install/..." path
9.7. Message "... perl.exe: *** fatal error - unable to remap ...\Glob.dll to
     same address as parent ..." or other kind of a message around a dll remap
9.8. Message "tar: ...: Cannot open: Permission denied"
9.9. Message from the configure script:
     "checking how to run the C preprocessor... /lib/cpp
     configure: error: C preprocessor "/lib/cpp" fails sanity check"
9.10. The Msys "mount" command prints mount points which are not found in the
     "/etc/fstab" file or changing the "/etc/fstab" file and restarting Msys
     shell does not affect mount points list printed by the mount command.
9.11. Message "rm: cannot remove `.../etc/fstab': Permission denied" or
     "... fork: Permission denied".
10. AUTHOR EMAIL

-------------------------------------------------------------------------------
1. DESCRIPTION
-------------------------------------------------------------------------------
The GnuBuilds is a project to support building of a make projects under the
cygwin, msys and mingw environments. It includes script wrappers around the
build and test scripts from the original sources package, and includes scripts
for automation of the "patch original sources", "pack the output binaries" and
"collect dependencies" targets including automatic logging of overall process.

-------------------------------------------------------------------------------
2. LICENSE
-------------------------------------------------------------------------------
The Boost license (see included text file "license.txt" or
http://www.boost.org/users/license.html)

-------------------------------------------------------------------------------
3. PROJECT TERMS
-------------------------------------------------------------------------------
"build scripts project package" -
  the package with set of the build scripts, tools and configuration files for
  the "build scripts base package".

"build scripts base package" -
  the package with set of scripts, tools and configurations files which is
  supported the basics of the project build environement.

"build scripts output package" -
  the archive package which is a result of build of a "build script project
  package".

"original sources package" -
  the package with original sources which can be built by the
  "build scripts project package". Basically includes sources of the related
  project distributed as is without any patched files or patches.

"original sources patch package" -
  the package with patches for the original sources which can be built by the
  "build scripts project package". Basically includes patches in predefined
  format described inside the package and required to build original source
  without critical errors or including needed functionality.

"project build environement" -
  build environment which is represented by the project build scripts directory
  tree, environment variables and running backend system declared in the OSTYPE
  variable.

-------------------------------------------------------------------------------
4. BUILD SCRIPTS DIRECTORY TREE
-------------------------------------------------------------------------------
<GnuBuildsRoot>        - the path to the root of the build scripts directory 
 |                       tree
 +- Build              - a build maintain directory, for example, to run the
 |                       compile.sh script from
 +- Config             - directory with the project basic configuration files
 |
 +- Help               - directory with the project related help files
 |
 +- Install            - directory where the binaries installed by run the
 |                       installation stage
 +- Output             - directory for all intermediate output, except
 |   |                   temporary files
 |   +- backups        - directory where stored all backup files
 |   |   |
 |   |   +- logs       - directory where stored archived logs from a previous
 |   |   |               build scripts run
 |   |   +- sources    - directory where stored archived part of the original
 |   |                   sources for the patch stage to automatic repatching
 |   |                   in a next patch stage run
 |   +- build          - directory where the build run
 |   |
 |   +- cache          - directory where stored the intermediate cache data
 |   |
 |   +- logs           - directory where stored the last build logs
 |
 +- Packages           - directory where stored installed binaries, logs and
 |                       other output in archived form for the distribution
 +- Projects           - directory where stored the build scripts project
 |                       packages
 +- Sources            - directory where stored the original sources packages
 |                       and the original sources patch packages
 +- Temp               - directory there mounted /tmp path and there pointed
 |                       the TMP and TEMP variables
 +- Tools              - directory where stored the build scripts base package

-------------------------------------------------------------------------------
5. INSTALLATION
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
5.1. Backends installation
-------------------------------------------------------------------------------
This section describes a common approach to the backend installation required
for the build system. Particular backend package versions is mentioned
in the README_EN.txt of a build scripts project package in the
"DEPENDENT BACKENDS" section.

-------------------------------------------------------------------------------
5.1.1. Cygwin
-------------------------------------------------------------------------------
Find the cygwin-XX.XX.XX.XX-XX_rvXX.zip package and unpack it somethere in the
temporary directory. Run included setup_X_XXX_XX_XX.exe setup and use this
configuration by steps:
1. Next
2. "Install from Local Directory"
3. Root Directory: "c:\Cygwin\1.5" (for example)
4. "Local Package Directory": "<PathToUnpackedDir>/Packages"
5. Next
6. Finish

After install check the "<CygwinRoot>/var/log/setup.log.full" file for a full
setup log, there is should be no errors.

Extract the "cygwin-update-XX.zip" archive to the "<CygwinRoot>" directory
confirming any overwrites.

-------------------------------------------------------------------------------
5.1.2. Msys
-------------------------------------------------------------------------------
Find the msyscore-XX.XX.XX.XX-XX_rvXX.tar package and unpack files from it in
order described below.

msys v1.0.11.0:
  msyscore-1.0.11.0-XX_rvXX.tar:
    msys/MSYS-1.0.11.exe
    msys/msysCORE-1.0.11-msys-1.0.11-base-bin.tar.lzma
    msys/coreutils-5.97-MSYS-1.0.11-snapshot.tar.bz2
    msys/bash-3.1-MSYS-1.0.11-1.tar.bz2
    <All other archives from the package, except below>
    msys/texinfo-4.13a-1-msys-1.0.11-bin.tar.lzma
    msys/termcap-20050421-MSYS-1.0.11-1.tar.bz2
  msys-update-XX.zip

All packages should be placed in one directory with relative paths preservation.
For example, you could place them in the "c:\msys\1.0" directory, otherwise
place in another directory and update the path in the
"<GnuBuildsRoot>/Config/msys.vars" file after.

-------------------------------------------------------------------------------
5.1.3. Msysdvlpr
-------------------------------------------------------------------------------
Find the msyscore-XX.XX.XX.XX-XX_rvXX.tar package and unpack files from it in
order described below.

msys v1.0.11.0:
  msyscore-1.0.11.0-XX_rvXX.tar:
    msys/MSYS-1.0.11.exe
    msys/msysCORE-1.0.11-msys-1.0.11-base-bin.tar.*
    msys/bash-3.1-MSYS-1.0.11-1.tar.bz2
    msys/coreutils-5.97-MSYS-1.0.11-snapshot.tar.bz2
    <All other archives from the package>
  msysDVLPR-1.0.0-alpha-1.tar.*
  msys-update-XX.zip
  msysdvlpr-update-XX.zip

All packages should be placed in one directory with relative paths preservation.
For example, you could place them in the "c:\msysdvlpr\1.0" directory, otherwise
place in another directory and update the path in the
"<GnuBuildsRoot>/Config/msysdvlpr.vars" file after.

-------------------------------------------------------------------------------
5.1.4. Mingw
-------------------------------------------------------------------------------
Find the mingw_rvXX.tar package and extract files from it in order described
below.

mingw_rvXX.tar:
  <All archives, except below>
  mingw/mingw-update.zip

All packages should be placed in one directory with relative paths preservation.
For example, you could place them in the "c:\mingw" directory, otherwise
place in another directory and update the path in the
"<GnuBuildsRoot>/Config/msys.vars" file after.

See README_EN.txt for details in the target build scripts project package.

-------------------------------------------------------------------------------
5.2. Build system installation
-------------------------------------------------------------------------------
See README_EN.txt from a build scripts project package for the details.

-------------------------------------------------------------------------------
5.2.1. Build scripts base package
-------------------------------------------------------------------------------
Unpack the "build_scripts_base_rvXX.zip" archive to the
"<GnuBuildsRoot>" directory.

-------------------------------------------------------------------------------
5.2.2. Build scripts project package
-------------------------------------------------------------------------------
Unpack a package to the "<GnuBuildsRoot>" directory.

-------------------------------------------------------------------------------
5.2.3. Original sources package
-------------------------------------------------------------------------------
Unpack an archive to the
"<GnuBuildsRoot>/Sources/<PathToSources>" directory.

-------------------------------------------------------------------------------
5.2.4. Original sources patch package
-------------------------------------------------------------------------------
Unpack an archive to the
"<GnuBuildsRoot>/Sources/<PathToPatches>" directory.

-------------------------------------------------------------------------------
6. USAGE
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
6.1. Config directory
-------------------------------------------------------------------------------
Go to "Config" directory in the unpacked build scripts and update if required
the "cygwin.vars" and "msys.vars" files for the correct absolute paths to the
Cygwin, Msys and Mingw system root directories.

-------------------------------------------------------------------------------
6.2. Run a build
-------------------------------------------------------------------------------
Open console window in the "Build" directory and run commands in this order:
1. "run_<OSTYPE>[_uac].bat"
2. cd "$OLDPWD"
3. ./compile.sh <ProjectName> <PlatformType> [<CompileArgs>]

Where:
<OSTYPE> - Type of the environment required to run a build.
[_uac] - Optional script modification runs the script in the UAC promoted
  environment. Has meaning only for the windows version higher than the
  Windows XP.
<ProjectName> - The build scripts project name, for example,
  "pthreads-2.8.0".
<PlatformType> - The build scripts project platform name, for example,
  "mingw-32-i686".
<CompileArgs> - The compile script additional arguments, see inside the
  "compile.sh" script for the details.

The last command should initiate the build, which will complete with files in
the "Install" and the "Packages" subdirectories. You always can interrupt a
build by the "ctrl-c" key press.

-------------------------------------------------------------------------------
6.2.1. Standalone build
-------------------------------------------------------------------------------
Standalone build may required installation for these set of backends (depends
on a package supported platforms):
1. Cygwin (platform target: cygwin-*)
2. Msys (platform target: mingw-*)
3. Msysdvlpr (platform target: msys-*)

You required to run the "install.bat" script included in an output package to
complete a package installation before use it.

-------------------------------------------------------------------------------
6.2.2. Integration build
-------------------------------------------------------------------------------
Integration build is not required explicit installation because used from a
backend system. After a build will done, just copy all binaries into the
"/usr/local" (or into the "/usr", depends on a package itself) directory in a
backend system.

Warning:
  The build scripts implementation doesn't support the install of an info-files
  from the info directory, so you required manually call the "install-info" for
  a backend system if you want to install the info documentation for a backend.

Note:
  Naming of an integration projects ends by the "integr" keyword.

-------------------------------------------------------------------------------
6.3. Run the build
-------------------------------------------------------------------------------
To read out how to build specific build scripts project package, see details
in the README_EN.txt in that build scripts project package.

-------------------------------------------------------------------------------
7. AFTER THE BUILD
-------------------------------------------------------------------------------
When the build is completed you need to check several things before use the
output package:
1. Use the install.bat script included into the output package to install or
   reinstall a package in a directory it placed, except of integration package
   which is not required of explicit installation.
2. If you want to use package as a standalone package then do copy to the
   output package /bin directory dependencies from the *-deps.tar.bz2 file. The
   binaries from the package with dependencies stored in several subdirectories.
   Dependencies which are found in the cygwin/msys subsystem and dependencies
   which are found in OSTYPEPATH variable. The first one basically stored in the
   /bin or /usr/bin subdirectories, second one - in the /usr/local. You need to
   find out which one you required to copy without overwrite confirm.

-------------------------------------------------------------------------------
8. Additional files
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
8.1 *.reg files
-------------------------------------------------------------------------------
The "Build" subdirectory includes several files for the Windows registry:
- win7_restore_wer_gui.reg
- win7_suppress_wer_gui.reg
- winxp_restore_wer_gui.reg
- winxp_suppress_wer_gui.reg

You may use them if you want to suppress any Windows Reporting GUI while a
build run.

-------------------------------------------------------------------------------
9. KNOWN ISSUES
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
9.1. Message about a command or a file that is not found.
-------------------------------------------------------------------------------
This could appear because:
1. The PATH variable doesn't include relative search paths now just, for
   example, like the current directory in the msys/mingw systems.

To fix that do update the PATH variable in the config.sh in the project with
the current directory search path.

-------------------------------------------------------------------------------
9.2. Patch stage blames that one or more patches were already applied, or
     couldn't apply because of error(s) about patch reversing
-------------------------------------------------------------------------------
That could appear because:
1. You removed the backup archive with original sources which was patched
   before: "<GnuBuildsRoot>/Backups/<ProjectPath>/<PlatformType>/Sources/
   <SubPathToTargetSources>/<SourcesRootDirName>.tar.bz2".
2. The backup archive with original sources is broken due to interruption in
   a previous run in the processes of it's generation or due to something else.
3. The target sources directory somehow before the patch stage
   did contain not original source files.

To fix that do manually rollback sources to the original state and ansure that
the above backup archive file is removed. Detailed steps about a package build
is described in the README_EN.txt of the target build scripts project package.

-------------------------------------------------------------------------------
9.3. Build script ignores to build one or more stages because already built them
-------------------------------------------------------------------------------
That could appear because:
1. You already built those stages before and tried to rebuild the project by
   call the compile.sh script before remove the cache file:
   "<GnuBuildsRoot>/Output/<ProjectPath>/<ProjectName>-<ProjectPlatformType>.cache"

To fully rebuild project try to remove the cache file.

-------------------------------------------------------------------------------
9.4. Sometimes the compile.sh script execution hangs after the ctrl-c press
-------------------------------------------------------------------------------
This happens basically in the Msys environment. To fix that you may use the
Process Explorer to close child hanged processes. This is not a bug in the
build scripts.

-------------------------------------------------------------------------------
9.5. The "<GnuBuildsRoot>/Temp" directory sometimes is not empty
-------------------------------------------------------------------------------
That happens because of bugs in downlevel scripts and tools running by the
build scripts and/or it may happen because of previous issue.

To fix that do check directory time to time or before a build, it must be empty
and may contain last temporary files which is not required for a next build run.

-------------------------------------------------------------------------------
9.6. The output package doesn't work and/or prints that it did not found
     something in the "/usr/local/install/..." path
-------------------------------------------------------------------------------
That may happens because the "/usr/local/install/<ProjectInstallName>" was not
properly mounted before of an output package usage. Read the "AFTER THE BUILD"
section for the details.

-------------------------------------------------------------------------------
9.7. Message "... perl.exe: *** fatal error - unable to remap ...\Glob.dll to
     same address as parent ..." or other kind of a message around a dll remap
-------------------------------------------------------------------------------
In some circumstances a cygwin packages requires rebase for a DLLs inside it.
See the "http://cygwin.wikia.com/wiki/Rebaseall" internet link or the
"<GnuBuildsRoot>/Help/Cygwin Wiki - Rebaseall.mht" file for the details for one
exception, use the "ash" shell instead of the "dash" shell described in the
article.

-------------------------------------------------------------------------------
9.8. Message "tar: ...: Cannot open: Permission denied"
-------------------------------------------------------------------------------
A file that the tar trying to read/write is not accessable in respect to the
permissions that the file has. Use "chmod" and "setfacl" tools to change
permissions on the file to grant access for the tar and other tools.

-------------------------------------------------------------------------------
9.9. Message from the configure script:
     "checking how to run the C preprocessor... /lib/cpp
     configure: error: C preprocessor "/lib/cpp" fails sanity check"
-------------------------------------------------------------------------------
That may happens because you tried to mount internal system path like the
"/usr/local" or the "/usr". To find out which one paths are mounted in a shell
session do run the "mount" command manually.

-------------------------------------------------------------------------------
9.10. The Msys "mount" command prints mount points which are not found in the
     "/etc/fstab" file or changing the "/etc/fstab" file and restarting Msys
     shell does not affect a mount points list printed by the mount command.
-------------------------------------------------------------------------------
That may happens because one or more Msys utilities was not properly closed and
left hanged in the process list as a "zombie" processes. The Msys system can
share mount points list between all Msys processes created in a session so you
must close all processes created after a session been run to enable mount points
list close too.
WARNING:
  Beware of multiple msys backends and don't try to run multiple msys sessions
  from different stores, because those sessions will share the same mount points
  list, overwise that may lead to unpredictable behaviour.

-------------------------------------------------------------------------------
9.11. Message "rm: cannot remove `...': Permission denied" or
     "... fork: Permission denied".
-------------------------------------------------------------------------------
That may happens because the file is created under UAC promoted
environment but the console was run in non UAC promoted environment.
To fix that:
- Run a console in UAC promoted environment, for example, by the script
  run_cygwin_uac.bat, run_msys_uac.bat or run_msysdvlpr_uac.bat.
- Remove the file manually.

-------------------------------------------------------------------------------
10. AUTHOR EMAIL
-------------------------------------------------------------------------------
andry at inbox dot ru