wiki:BuildNotes

Building UltraScan from source

UltraScan is built using Qt ( http://trolltech.com/products/qt/features/library/index ) as a cross platform application. The package is available for several different hardware architectures and operating systems. This page describe the procedures to build the system in Unix/Linux? and Windows.

The overall design of UltraScan is to have a fairly large class library and multiple executables (about 75) that are generally very short stubs that call the appropriate library resources.

The directory setup is generally:

develop/
  src/
  include/
  us_<specific function>/

To create a library or application using Qt, a .pro (profile) file is used to describe the details of the build process. UltraScan uses a set of these files:

  • libus.pro - The procedure to build the library.
  • us_all.pro - A procedure to build all the programs in the us_<specific function>/ directories
  • individual .pro files

The .pro files have the capability to adjust to the environment, so a common set of files is used for both Linux / UNIX, Macintosh, and Windows platforms. As of this writing, the Macintosh functionality has not been tested for the current version.

The individual .pro files are quite similar and most of the details are in a .pri (profile include) file. For instance, the us_admin.pro file consists of only:

!include ( ../generic.pri ) error( "../generic.pri missing.  Aborting..." )

TARGET  = us_admin

The .pro files are processed by qmake. This application, a part of Qt, uses an auxillary file, $QTDIR/mkspecs/<arch>-<compiler>/qmake.conf for many of its defaults. The defaults can be overridden in the .pro files.

Linux / UNIX

Building for Linux consists of running

qmake libus.pro
make

./make_mf
qmake us_all.pro
make

qmake generates a Makefile. The make_mf script goes through all the us_* directories and runs 'qmake us*.pro'.

When installing UltraScan, the Qt libraries and the auxiliary qwt (customized) and qwtplot3d libraries must be available through the normal /etc/ld.so.conf paths or set via the LD_LIBRARY_PATH environment variable.

UltraScan also uses the standard tar and gzip programs and their associated libraries.

Windows

Building UltraScan on windows is very similar. The same qmake and make_mf (the make_mf script needs to be run under bash in Cygwin) programs are run, however the output is different. The output for libus and the individual programs are .vcproj (Visual C++ Project) files. The output for us_all.pro is a .sln (Visual Studio Solution file).

These libus.vcproj and us_all.sln files are then loaded into visual studio and the build process creates the .dll and .exe files.

There are a couple of 'gotchas' in this process. Visual Studio has two main modes: Debug and Release. There is a bug in the Qt-3.3.8 qmake routine that puts the wrong path for the target file in the Release build of the .vcproj file. This needs to be overridden manually ( change Release\ to ..\..\bin\ ) and is fixed in the make_mf script for individual executables. The library release path needs to be set manually (..\bin\libus.dll ). Also, the .vcproj files are always generated with a default of Debug (even when the .pro file specified release), so that needs to be updated to Release manually (all 75+ files) when preparing for deployment. Fortunately, this can be done fairly quickly on one page via check boxes and a bit of scrolling.

The Microsoft compiler also generates a lot of extra files (.manifest, .res, .idb, .dep, and others). Most of these are set up in the .pro files to be put into Debug/ and Release/ subdirectories of the program being generated, but the .lib and .exp files generated with .dll files are in the target directory. These are required for satisfying library entries when building, but are not necessary for deployment.

Emre's attempt at getting windows compilation to work on a fresh win7 box

Windows Libraries

In Windows the path to find libraries is confusing. The easiest way to deploy a library is to put the required dll files in the executable directory (bin/) which is searched by default. The tar and gzip executables from Cygwin need to be placed in the bin/ directory as well as the Cygwin libraries cygiconv-2.dll, cygintl-8.dll, and cygwin-1.dll.

Visual Studio does have a nice utility to determine library dependencies for an executable or a library named 'depends'. It can tell what libraries are needed, including any optional libraries that may be loaded. ( We can safely ignore the warning about the java dll that is missing. )

This was used to find that Visual C++ libraries are also needed. These need to be placed in the bin/ directory as suggested by TrollTech:

http://doc.trolltech.com./4.1/deployment-windows.html#visual-studio-2005

"... include the runtime libraries. To do this, copy the contents of

<Visual Studio Install Path>\VC\redist\<Architecture>\Microsoft.VC80.CRT

into the folder where your executable is."

In addition the Qt mysql plugin, qsqlmysql.dll, must be in a subdirectory, sqldrivers\ and there must be a copy of the directory Microsoft.VC80.CRT\ in sqldrivers\.

Although not tested, it is possible that the mysql drivers could be built into the qt-mt338.dll library, in which case the sqldrivers\ subdirectory may not be necessary at all. This would be the preferred method when UltraScan is upgraded to Qt4.

Building for Windows Release (Draft)

This is from an email describing how we produce a Windows release.

Click on the Cygwin icon on the Desktop.

cd to /cygdrive/e/ultrascan/develop

svn update

sh revision.sh

Edit libus.pro, generic.pri using your favorite text editor to make sure 'release' is set, not 'debug'

qmake libus.pro

qmake us_all.pro

sh make_mf

Now launch Visual Studio

Click File -> Open -> Project/Solutions, navigate to E:/ultrascan/develop/libus.slrn and wait for a few seconds for the
project file to load.

Click on Build -> Solution (or just press F7)

Once its finished, click on File -> Close Solution

Load the us_all project file and the same as above,
Build -> Solution (or F7).

Here's where it gets kinda funky..... In Debug mode, libus goes into
develop\Debug but the EXE files stay in bin.

Go back to the Cygwin console and cd to /cygdrive/c/dist

This is the package build directory. You will need to copy bin etc and doc to this directory:

cp /cygdrive/e/ultrascan/etc/* etc/.
cp /cygdrive/e/ultrascan/doc/* doc/.
cp /cygdrive/e/ultrascan/bin/* bin/.

To check the official build, double click on the Desktop icon labeled "UltraScan on dist".

Now remove the .svn directories and unneccesary stuff from etc:

find . |grep .svn |xargs rm -rf

To make the official package

Click on "CreateInstallFree" on the Desktop

Click on "Output" and change "Setup Executable" to the new revision number

Click on Setup -> Make to build the package. Once finished, it will be in the My
Documents directory.

Windows 7

At the moment we are left with a less-than-ideal version of the Qt-3.3.8 source code that will work under Windows.

Notes about this version:

  • It is already compiled using MSVC 2005 under Windows XP. Some files from the original distribution appear to be missing.
  • It compiled as a debug version, and we need a release version to package correctly. To accomplish this we need to recompile it "in place," that is, using files that are already there until replacements are created.
  • Other available versions, such as the X11 free version, are missing files necessary to compile under Windows.
  • There are no open source versions of Qt v.3 for Windows currently available. Web links to it are either the previously-mentioned X11 free version or are broken.

Notes about how to create a Qt-3.3.8 release version from what we have:

  • VS 2005 needs to be patched to work under Windows 7. Install service pack 1 and then these patches:
    • VS80sp1-KB926601-X86-ENU.exe
    • VS80sp1-KB932232-X86-ENU.exe
  • Set up mysql before Qt
  • Go into the src subdirectory and make sure that in qt.pro it is set up as a release version
  • When compiling in the VS command line window or in Visual Studio, right-click on the icon and run as administrator
  • Be careful about the differences between Windows XP and 7. Most perplexing for what we are doing here are file ownerships and permissions. For instance, be careful about files owned by Administrators vs. by the individual user (Admin). Some processes will act like they have completed when they have actually failed due to permissions. Watch the dates on files and change ownership to the Admin user where necessary.
  • Run configure from the base install directory and then go to the qmake subdirectory and run nmake there. This process fails as part of the configure command because it assumes make instead of nmake. This will build a new qmake command. Make sure that this new qmake is copied to the bin directory. Example configure command:
    bin\configure -spec win32_msvc2005 ^
                  -release             ^
                  -shared              ^
                  -no-exceptions       ^
                  -thread              ^
                  -stl                 ^
                  -qt-gif              ^
                  -qt-imgfmt-png       ^
                  -qt-imgfmt-mng       ^
                  -qt-imgfmt-jpeg      ^
                  -qt-png              ^
                  -qt-mng              ^
                  -qt-jpeg             ^
                  -system-zlib         ^
                  -vcproj              ^
                  -no-qmake            ^
                  -qt-sql-mysql
    
  • While you may choose to use the Cygwin window for file management, try to run qmake and nmake from the VS command line. Qmake will sometimes work from Cygwin and sometimes not.
  • Make sure the Windows INCLUDE, LIB, QMAKESPEC, PATH, QTDIR, QWTDIR, and QWT3DDIR variables are set properly. Examples:
    INCLUDE=c:\Qt\3.3.8\include;c:\mysql-5.5\include;c:\Qt\3.3.8\src\3rdparty\libjpeg; ^
            c:\Qt\3.3.8\src\3rdparty\libpng;c:\Qt\3.3.8\src\3rdparty\zlib;c:\Users\Admin\Documents\my_includes;
    LIB=c:\Qt\3.3.8\lib;c:\mysql-5.5\lib;
    QMAKESPEC=win32-msvc2005
    PATH=%PATH%;c:\Qt\3.3.8\bin;c:\mysql-5.5\bin;
    QTDIR=c:\Qt\3.3.8
    QWTDIR=c:\Qwt-US2
    QWT3DDIR=c:\qwtplot3d
    
  • Create a directory for other include files (c:\Users\Admin\Documents\my_includes). Create a file there called unistd.h with the following contents:
    #ifndef _UNISTD_H
    #define _UNISTD_H    1
    
    /* This file intended to serve as a drop-in replacement for
     *  *  unistd.h on Windows
     *   *  Please add functionality as neeeded
     *    */
    
    #include <stdlib.h>
    #include <io.h>
    #include <getopt.h> /* getopt from: http://www.pwilson.net/sample.html. */
    
    #define srandom srand
    #define random rand
    
    const W_OK = 2;
    const R_OK = 4;
    
    #define access _access
    #define ftruncate _chsize
    
    #define ssize_t int
    
    #define STDIN_FILENO 0
    #define STDOUT_FILENO 1
    #define STDERR_FILENO 2
    
    #endif /* unistd.h  */
    
  • After establishing a build environment, run nmake clean to clean out older compiled files and to regenerate release-mode Makefiles and or VS project files (*.vcproj). It will miss some files, for instance precompiled headers (*.pch). These can be deleted too. Be careful not to delete the files in the bin and lib directories---these files are needed until replacements can be created.
  • nmake recompile everything. There will be errors in this process; continue at least until qt-mt.dll, qt-mt.lib and libmysql.dll are built. Other components can either be disabled, or just stop.
  • More funky stuff: sometimes it's looking for qt-mt.dll and other times qt-mt338.dll. Same with qt-mt.lib. It's easy just to copy them. Some files need to be in lib sometimes, and bin other times. For instance mysql.dll.
  • Compile qwt and qwtplot3d more or less the same way.
  • Compile UltraScan files using procedure above under Building for the Windows Release, adjusting for file locations.
  • Edit the TEMPLATE line in the appropriate *.pro file as desired before running qmake. For instance if you say it's a vclib qmake will generate vcproj files which need to be compiled in the Visual Studio environment. Or you can just call it a lib and qmake will generate a Makefile for you, which you can compile with nmake at the VS command line. Be sure to check your make files before compiling---qmake always generates a file called Makefile, which you might want to rename to Makefile.libus if you are working with the library. Also check dates on files to make sure the right file was generated; it's easy to have vclib in the *.pro file (no Makefile generated) and then run nmake. There is probably an old Makefile in there that will be used.
  • Make sure to distribute the corresponding manifest file with each dll or exe.
  • Both the CRT and MFC directories (from "c:\Program Files\Microsoft Visual Studio 8\VC\redist") should be distributed in the bin directory along with all the executable files. By distributing them here we should be able to avoid the side-by-side issues; this way they are actually beside the files that are calling them, and they remain private copies.
Last modified 6 years ago Last modified on Mar 24, 2012 6:45:10 PM