wiki:BuildInstructions

UltraScan III Build Instructions

Setting up a Windows Build Environment

This procedure has been tested under Windows 7 32-bit, but it should work under XP also.

  • Download the latest version of GNU g++/MinGW for Windows here. Version tested: 4.4.
  • Download and install the latest version of MSYS for Windows here. Version tested: 1.0.11. Install at least the Core and DTK libraries. Make sure you can start a bash shell as described there and use it to compile with the GNU tools.
  • Sample system environment variables:
    PATH=%PATH%;c:\mingw\bin;c:\Qt\4.7.3\bin;c:\mysql-5.5\bin;c:\Depends;c:\Users\Admin\Documents\ultrascan3\bin;c:\doxygen\bin;
    INCLUDE=c:\mingw\include;c:\Qt\4.7.3\include;c:\mysql-5.5\include;
    LIB=c:\Qt\4.7.3\lib;c:\mysql-5.5\lib;c:\Users\Admin\Documents\ultrascan3\lib;
    QMAKESPEC=win32-g++
    QTDIR=c:\Qt\4.7.3
    QWTDIR=c:\Qwt-5.2.2
    
  • Download the latest version of OpenSSL here. Version tested 1.0.0d. Compile from source using the MinGW build environment. That way when linking programs that use them the MinGW linker will recognize the exports. Pay close attention to the build instructions, for instance you have to run tar and ./config from the MSys shell. Additionally, the instructions say it needs Perl to install. Version tested: Perl version 5.6.1 built for msys. Another option: ActiveState Perl from http://www.activestate.com/ActivePerl
  • The .a files are the export libraries and the pc files are the dlls. Create an openssl directory like this:
    cd /cygdrive/c
    mkdir openssl
    cd openssl
    mkdir -p bin lib include/openssl
    cp ../Download/openssl-1.0.0d/include/openssl/* ./include/openssl
    cp ../Download/openssl-1.0.0d/libssl.a ./lib/ssleay32.a
    cp ../Download/openssl-1.0.0d/libssl.pc ./bin/ssleay32.dll
    cp ../Download/openssl-1.0.0d/libcrypto.a ./lib/libeay32.a
    cp ../Download/openssl-1.0.0d/libcrypto.pc ./bin/libeay32.dll
    cp ../Download/openssl-1.0.0d/apps/openssl.exe ./bin
    
  • Download the latest version of Qt here. Version tested: This binary installer configured for MinGW (version 4.7.3).
  • Download the latest version of Qwt here. Version tested: 5.2.2. Version 6.0.1 seems enough different to avoid for right now. Edit the qwtconfig.pri file and make sure you're building the release version
  • Qt Single Application is needed, but is no longer supported by Qt. Find code from previous installation.
  • Qwtplot3d is now a part of the US3 svn archive and is built as a separate library from there as a part of the US3 build. This has minor changes to update the patch level when building from the original source qwtplot3d-0.2.7m.tgz. Be sure to change the TEMPLATE variable in qwtplot3d.pro from vclib to lib.
  • MySQL's source build environment in Windows supports only Visual Studio, so it's easier to install the binary package and then convert the export library for use with MinGW. Install the MinGW Utilities from source and to avoid a bug turn optimization off in the reimp module. Copy the resulting files to c:\mingw\bin and follow a procedure like the following:
    reimp -d c:\mysql-5.5\lib\libmysql.lib
    dlltool -k --input-def libmysql.def --dllname libmysql.dll --output-lib libmysql.a
    
    Now the MinGW export library should in libmysql.a. If that doesn't work, you can bypass the reimp command and create the def file by hand:
    strings libmysql.lib |grep __imp__ |sed "/s^__imp__//" >libmysql.def
    
    The exports appear twice in this file, so delete the duplicate information and then at the top of the file insert:
    LIBRARY "libmysql.dll"
    EXPORTS
    
    Then follow with the dlltool command. One way or the other, this removes some extra leading name mangling produced by MSVC but not understood by MinGW.
  • Build the Qt MySQL plugin in c:\Qt\4.7.3\src\plugins\sqldrivers\mysql by first adding something like this to mysql.pro
    MYSQLDIR      = c:/mysql-5.5
    INCLUDEPATH  += $$MYSQLDIR/include
    LIBS         += -L$${MYSQLDIR}/lib -lmysql
    

Then build the plugin with qmake/make. Be sure to change to release mode in ../../qsqldriverbase.pri.

  • You will also need the Visual C++ 2008 Redistributable Package, available for download at http://www.microsoft.com/download/en/details.aspx?id=29.
  • Download and install Dependency Walker to investigate missing dependencies.
  • Consider adding a DWORD value called AlwaysUnloadDll = 1 in HKLM/Software/Microsoft/Windows/CurrentVersion/Explorer and restart the computer. Otherwise debugging dll code can be tricky because the old one won't be unloaded automaticallly. Alternatively, cd to the directory where the dll is located and try to unload the dll as follows:
    regsvr32 -u dllname.dll
    
  • Download and install DOxygen.

Creating a Windows XP/7 Release

This procedure works using the Windows7-MinGW-US3 VM setup, as outlined above. First of all, we are required to use two command-line windows, one Cygwin window and an MSys window. MSys is associated with the standalone MinGW Windows libraries. Perhaps it is a bit cumbersome to go back and forth between two windows, but Cygwin cannot be made to work with a standalone MinGW. It has its own implementation of that, and if we tried to use it that way we would end up needing to distribute pieces of Cygwin, include its license agreements, and so forth. Similarly, if you try to use MSys for routine file management you will likely run into its limitations fairly quickly.

Setting up your compile environment:

  • Open a Cygwin window and an MSys window (the big "M" on the desktop). Right-click and select "Run as Administrator" for both.
  • Use the Cygwin window for file management, svn updates, editing in vi, secure copying and so on. Cygwin is a more robust implementation of the Linux environment in Windows than MSys is.
  • Use the MSys window to compile using the standalone MinGW Windows libraries. Navigation in the MSys window is similar to Cygwin, except that the drives are referred to as /c/directory/subdir (instead of /cygdrive/c/directory/subdir). You can call "make" in individual directories or use the "makeall.sh" or "makeallclean.sh" scripts in the base ultrascan3 directory.
  • After logging in as the Admin user, the code base is at /cygdrive/c/Users/Admin/Documents/ultrascan3.

Notes on building:

  • When building UltraScan III in this environment, the libraries are created in the lib subdirectory. The .a files are the export libraries and should stay there so that they can be found if you want to execute a program from this code base. The .dll files need to be moved to the ../bin directory.
  • Be careful not to delete everything from the lib and bin directories when developing. There are a few files in there that are not part of UltraScan directly but are still needed.
  • Start by going to the ultrascan3/programs/us directory and run the revision.sh program to create the revision include file.
  • Next run makeall.sh. A clean compile at this stage will still have two errors, one for us.exe and the other for us_helpdaemon. These are programs that use QtSingleApplication.
  • There is a Qt bug that manifests itself when working with QtSingleApplication. After running qmake, edit the appropriate makefile (Makefile.Release) and find code that looks like this (after ####### Compile):
    obj/us_helpdaemon.o: us_helpdaemon.cpp c:/Qt/4.7.3/addons/qtsingleapplication-2.5_1-commercial/src/QtSingleApplication \
        c:/Qt/4.7.3/addons/qtsingleapplication-2.5_1-commercial/src/qtsingleapplication.h \
        us_helpdaemon.h \
        ../../utils/us_settings.h \
        ../../utils/us_extern.h
      $(CXX) -c $(CXXFLAGS) $(INCPATH) -o obj/us_helpdaemon.o us_helpdaemon.cpp
    
    Change it so that it looks like this:
    obj/us_helpdaemon.o: us_helpdaemon.cpp \
        c:/Qt/4.7.3/addons/qtsingleapplication-2.5_1-commercial/src/qtsingleapplication.h \
        us_helpdaemon.h \
        ../../utils/us_settings.h \
        ../../utils/us_extern.h
      $(CXX) -c $(CXXFLAGS) $(INCPATH) -o obj/us_helpdaemon.o us_helpdaemon.cpp
    
    In other words, take out the QtSingleApplication dependency in the make file and run make. Make sure you don't run qmake in there or you will have to edit the file again. Maybe we can figure out a better way around the bug, but this seems to work. QtSingleApplication is not supported by Qt any more.
  • For the moment the manual documentation cannot be built correctly. Copy up-to-date manual.q* files from another place to bin.

Packaging the Windows Installation File

This procedure is relatively straightforward. Continue using the Windows7-MinGW-US3 VM setup and follow these steps:

  • Copy all the files from the ultrascan bin and etc directories to the /cygdrive/c/dist bin and etc directories. I suggest not deleting what is in there already---there are a number of Qt dlls that are needed for the program to function on a computer that doesn't already have Qt installed.
  • Open up the "CreateInstall Free" program on the desktop. It should remember all the settings from the last time.
  • Click on the "Output" menu item and change the version number in the "Setup Executable" field.
  • Click on the fourth icon over (the setup icon) and let it create the executable. It should end up in /cygdrive/c/setups.

Ubuntu Build Notes

Building Ultrascan3 on Ubuntu basically follows steps for building on Linux (see below). Here are some important details on building using the latest Qt5 library.

  • Download latest Qt5 version (Qt-5.7.0) and get opensource version: http://download.qt.io/official_releases/qt/5.7/5.7.0/single/qt-everywhere-opensource-src-5.7.0.tar.gz
  • Download the latest version of Qwt - we tested Qwt-6.1.2, https://sourceforge.net/projects/qwt/files/qwt/6.1.2/qwt-6.1.2.zip/download
  • Make sure you have installed the following libraries: openSSL, postgreSQL, and MySQL
  • You will need a working OpenGL environment
  • Install the following font files in Ubuntu: libfontconfig1, libfontconfig1-dev, libfreetype6, libfreetype6-dev, fonts-dejavu
    • Centos 7 specific notes:
      • include path for openssl: export OPENSSL_LIBS='-L/usr/lib64 -lssl -lcrypto'
      • in /usr/lib64 make symbolic links: ln -s libssl.so.1xxx libssl.so && ln -s libcrypto.so.1xxx libcrypto.so
      • to enable plugin-sql-mysql && plugin-sql-psql the postgresql-contrib, postgresql-devel need to be installed
      • export LD_LIBRARY_PATH=/usr/lib64 && PATH=/usr/include:/usr/include/mysql:/usr/include/GL
      • install openGL (if not already) as: yum install freeglut-devel

Qt-5.7.0 building:

tar -zxvf qt-everywhere-opensource-src-5.7.0.tar.gz
cd qt-everywhere-opensource-src-5.7.0
  • Execute the following configuration file to make sure you have everything needed for UltraScan development:
    bash ./myconfig.sh
    

Content of ./myconfig.sh: (change path in OPENSLL_LIBS to that pointing to libssl.so and libcrypto.so)

#!/bin/bash
export OPENSSL_LIBS='-L/lib/x86_64-linux-gnu -lssl -lcrypto'
./configure -prefix /opt/qt-5.7.0 -release -opensource -confirm-license \
 -platform linux-g++-64 \
 -nomake tests -nomake examples \
 -opengl desktop \
 -qt-xcb \
 -plugin-sql-mysql -plugin-sql-psql -openssl-linked \
 -system-proxies \
 -D QT_SHAREDMEMORY -D QT_SYSTEMSEMAPHORE \
 -no-icu \
 "$@"
  • As the root user, make and install Qt-5.7.0:
    make
    make install
    

  • To build Qwt:
    unzip qwt-6.1.2.zip
    cd qwt-6.1.2
    /opt/qt-5.7.0/bin/qmake
    

Important: use qmake of the newly compiled Qt-5.7.0 you are going to use to build Ultrascan. Repeat the last step for /src and /designer directories:

cd qwt-6.1.2/src
/opt/qt-5.7.0/bin/qmake
cd ../designer
/opt/qt-5.7.0/bin/qmake
  • Export paths Ultrascan3 depends on. Example of the necessary portion in the ~/.bashrc file:
    QTDIR=/opt/qt-5.7.0
    QWTDIR=/usr/local/qwt-6.1.2
    QMAKESPEC=linux-g++-64
    unset QTMAKESPEC
    
    US3DIR=${HOME}/ultrascan3
    QTBIN=${QTDIR}/bin
    QTLIB=${QTDIR}/lib
    QTINC=${QTDIR}/include
    US3BIN=${US3DIR}/bin
    US3LIB=${US3DIR}/lib
    QWTLIB=${QWTDIR}/lib
    
    #       set PATH, LD, QTDIR, and others  for US-3 and Qt-5                                                                                            
    OPATH=`echo $PATH|sed -e 's@^.*:/opt/intel@opt/intel@'`
    OLPATH=`echo $LD_LIBRARY_PATH|sed -e 's@^.*:/opt/intel@opt/intel@'`
    PATH=${US3BIN}:${QTBIN}:${OPATH}:$PATH
    LD_LIBRARY_PATH=${US3LIB}:${QTLIB}:${QWTLIB}:${OLPATH}
    ULTRASCAN=${US3DIR}
    us3=${ULTRASCAN}
    MAKEFLAGS="-j 24"
    
    export PATH LD_LIBRARY_PATH QTDIR QWTDIR ULTRASCAN QMAKESPEC us3 MAKEFLAGS
    

The above script implies Qt5 is installed in /opt/qt-5.7.0, Qwt installed in /usr/local/qwt-6.1.2, Ultrascan3 (to be) installed in $HOME/ultrascan3.

Since Qt version 5.7.0 the fonts directory is no longer set up by the make process. Without it Ultrascan will work but dialogs will be blank! To overcome this inconvenience, we can use the fonts installed by the fonts-dejavu package, as follows:

cd /opt/qt-5.7.0/lib
ln -s /usr/share/fonts/truetype/dejavu fonts

  • Retrieve the !UltraScan3 source code with:

svn checkout svn+ssh://bcf.uthscsa.edu/ultrascan3/trunk ultrascan3

Build with:

bash makeall.sh

Linux Build Notes

For Linux, use the following support libraries at the specified versions or later

  • The latest version of Qt (4.8.0) doesn't work with these instructions; use version 4.7. The Qt downloads Page is here. Version tested: This source code (version 4.7.4).
  • Download the latest version of Qwt here. Version tested: 5.2.2. Version 6.0.1 seems enough different to avoid for right now. Edit the qwtconfig.pri file and make sure you're building the release version
  • Qt Single Application is needed, but is no longer supported by Qt. Find code from previous installation.
  • Qwtplot3d is now a part of the US3 svn archive and is built as a separate library from there as a part of the US3 build. This has minor changes to update the patch level when building from the original source qwtplot3d-0.2.7m.tgz.

Building Qt:

on CentOS 6.7 gstreamer may be missing, install before building qt:

yum install 'pkgconfig(gstreamer-app-0.10)'
  • Use a configure command like the following to be sure to have everything you need for UltraScan development:
     ./configure -prefix /opt/qt-4.7.4 \
     -debug-and-release \
     -developer-build   \
     -qt-sql-mysql      \
     -nomake examples   \
     -nomake demos      \
     -opengl            \
     -fontconfig        \
     -system-proxies    \
     -svg -v
    
  • Check to make sure fontconfig-devel is installed, to get fonts.
  • To set a system proxy, export http_proxy=http://myproxy.com:8080
  • As the root user, make and install Qt:
    gmake
    gmake install
    
  • To make upgrading Qt easier the next time, create a symbolic link in /opt as follows:
    ln -v -sfn /opt/qt-4.7.4 /opt/qt
    
  • Install qwt: http://qwt.sourceforge.net/qwtinstall.html - a stock install of qwt-5.2.2 (http://bcf2.uthscsa.edu/packages/qwt-5.2.2.tar.gz) is known to work.
  • Now set up paths in /etc/profile or $HOME/.bash_profile using the symbolic link:
    QTDIR=/opt/qt
    PATH=$PATH:/opt/qt/bin
    QMAKESPEC=/opt/qt/mkspecs/linux-g++
    QWTPATH=/usr/local/qwt-5.2.2
    
  • Use the same idea in local.pri, below. That way, the next time you compile a new version of Qt, just change the symbolic link to point to the new directory and all the other configuration will follow
  • To build the documentation you will need graphviz (http://graphviz.org/) and the Perl Template library. Install the latter with "cpan Template". On CentOS you can install with:
    yum install perl-Template-Toolkit
    
    or from source at http://www.template-toolkit.org

Notes on compiling (Linux):

  • Copy local.pri.template to local.pri, and edit QWTPATH, SINGLEDIR, MYSQLDIR, and MYSQLPATH to point to the directories where QWT, QtSingleapplication, the MySQL binary, and the MySQL include files are actually installed.
  • Add QWT3D = ../qwt3dplot-qt4. This way $$QWT3D can be used to refer to it in libraries and ../$QWT3D in gui applications
  • Use ldd and ldconfig to verify/install libraries
  • Open ssl libraries (libcrypto.so, libssl.so) must be available.

The doxygen documentation generator is also recommended to generate current API html documentation files. Download doxygen at http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc

The libraries and include files must be available in directories searched by gcc. The following locations are recommended for use with the qt profile files:

/usr/local/lib/

libqwt.so -> libqwt.so.5.1.1
libqwt.so.5 -> libqwt.so.5.1.1
libqwt.so.5.1 -> libqwt.so.5.1.1
libqwt.so.5.1.1

ultrascan3/qwtplot3d-qt4 (source - libraries will be placed in ultrascan3/lib/)

libqwtplot3d.so -> libqwtplot3d.so.0.2.7
libqwtplot3d.so.0 -> libqwtplot3d.so.0.2.7
libqwtplot3d.so.0.2 -> libqwtplot3d.so.0.2.7
libqwtplot3d.so.0.2.7

/usr/local/include/
qwt

All Qt libraries

/opt/qt-4.7.0/include/
Qt include files

/opt/qt-4.7.0/addons/qtsingleapplication-2.5_1-commercial/
Expansion of qtsingleapplication tar file

Retrieve the UltraScan III source code with:

svn checkout svn+ssh://bcf.uthscsa.edu/ultrascan3/trunk ultrascan3

Build with:

bash makeall.sh

For 64-bit Linux environments, edit the local.pri and change the 64bit MySQL library location:

MYSQLDIR = /usr/lib64/mysql

For multi-node Linux environments like bcf, if you want to enable multi-node globus compiling, edit the local.pri file and enable the following lines:

  QMAKE_CXX  = distcc g++
  QMAKE_CC   = distcc g++
  QMAKE_MOC  = distcc $(QTDIR)/bin/moc
  QMAKE_UIC  = distcc $(QTDIR)/bin/uic
  QMAKE_LINK = distcc g++

Also, if desired, create the following environment variable, changing the -j parameter appropriately:

   export MAKEFLAGS=-j44

Mac Build Notes

Notes on building the Mac version of UltraScan III

  1. Building
  • After an "svn update", the total build is as on any platform: from ultrascan3,
    ./makeall.sh
    
  • The makeall.sh script now has special Mac commands, including calls to libnames.sh and appnames.sh.
  • If you make selective updates and rebuild either the utils or the gui library, you must run
    libnames.sh
    
  • Similarly, any application rebuilds require you run
    appnames.sh
    
  • Get and build the newest SOMO revision
    cd $us2
    svn update
    cd $us3
    ./somoupd.sh
    
  • If there were no UltraScan II updates for SOMO, but you want to have the US3 revision number updated or you make a source change to converted source, you can skip the somoupd.sh step. But you will still want to do the make steps.
    cd $us3/somo/develop
    ./revision.sh
    qmake libus_somo.pro
    make
    qmake us_somo.pro
    make
    cd ../
    bin/libnames.sh
    bin/appnames.sh
    
  • Test the reliability of the build by running us from $HOME/us3/ultrascan3/bin or by single-clicking its icon in the Dock.
  1. Creating the install
  • Copy selected contents of the ultrascan3 folder to a pkg/ultrascan3 folder.
    cd $us3
    ./copypkg-mac.sh
    
  • From Disk Utility, create a DMG; 177 MB in size; give a Save As value something that shows version, such as "us3-Mac-1344-1920" and give a Name of something like "UltraScan III Mac revision 1344-1920".
  • Open a Finder window and click on the disk image shown to the left to open the empty image folder.
  • Copy the Read Me First RTF file and UltraScanIII Installer package in the pkg/ folder to the DMG you created.
  • Compress the DMG (from a right-mouse-button-click menu) to get a .dmg.zip file.
  • Copy the *.dmg.zip file to the download site on ultrascan3 and edit the download.php file appropriately.
  1. Additional notes
  • The above notes are based on the environment and directory structure that exist on Jeremy's Mac mini under the /Users/garygorbet directory.
  • That is, the build takes place in /Users/garygorbet/us3/ultrascan3 .
  • Selected contents of the ~/us3/ultrascan3/ directory are copied to ~/us3/pkg/ultrascan3 .
  • The contents of ~/us3/pkg are copied to the disk image.

  • If the build is done in another user's home directory, the environment and structure should be similar.
  • To create a disk image that ultimately forms the install file, open Disk Utility by single-clicking on it in the Dock; then:

. Click on New Image in the upper tool bar.

. Fill in values like "Us3-Mac-1344-1920" in the Save As: and "UltraScan III Mac revision 1344-1920" in the Name: fields.

. Choose Desktop in the Where: combo box.

. Select a Size: value of 177.

. Leave other fields as defaulted and click the Create button.

. Double click on the resulting disk image to open a Finder window to which to copy the RTF file and Installer package from the pkg/ folder.

  • Once you have populated the disk image, right-mouse-click on it and eject it. It will have changed the contents of the .dmg file on the desktop.
  • Create the .dmg.zip file by right-mouse-clicking on the .dmg file and releasing on the "Compress ..." line.
  • You can perform any editing or command entry in the normal Unix way from within a Terminal window. You can open as many as you need by single-clicking on Terminal in the Dock.

Last modified 4 weeks ago Last modified on Oct 24, 2018 6:01:32 AM