$Id: README,v 1.21 2008/02/22 00:35:30 hvengel Exp $

 THIS SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
 EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
 WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

 IN NO EVENT SHALL ANYONE WHO HAS ANY PART IN THE DEVELOPEMENT OR
 DISTRIBUTION OF THIS SOFTWARE BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
 INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES
 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR
 NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
 LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
 OF THIS SOFTWARE.

 LProf is distributed under the

                GNU GENERAL PUBLIC LICENSE VERSION 3

 See file COPYING for details of LProf license.  In addition, the LProf sources 
 contain some source files from other projects.  All of these use either a GPL or 
 LGPL license version 2 or 3 or some less restrictive license.  These include:

   ArgyllCMS - GPLv3 license.

   solvopt - Is redistributed in LProf under GPLv2 by permission of it's authors.

   lcms - A modified version of lcms is included in the LProf source tree.  lcms 
          uses the MIT license.  See src/lcms/COPYING for details. 

   The above are all statically linked into LProf.

   For any binary version of LProf distributed after version 1.11.4.x a
   tarball containing the sources of all non-compiler runtime libraries 
   included in the installation binary will be made available on the LProf 
   download page for as long as that binary version is also available on 
   that page.  By installing the binary users are acknowledging that they 
   have been notified of the existence of this source code tarball and by 
   not downloading a copy of the tarball they are waiving any rights 
   granted under the GPL license to get that specific version of the 
   source code.

   This is the 5th. public release of the profilers. It has not been
   tested extensively, so is possible some bugs still exist.
   If so, sorry for the inconvenience, and please feel free to submit
   any suggestion/solution (if you can find it) in the LProf discussion
   forum at:

         http://sourceforge.net/forum/forum.php?forum_id=488887

   The main site for the package is located at

         http://sourceforge.net/projects/lprof

  This site has a tracker for reporting bugs, another tracker for
  making enhancement requests and one for submitting patches.  Please feel 
  free to use these.  The developers regularly review the contents of these 
  trackers and respond to bug reports and enhancement requests as quickly as 
  possible.

  Requirements
  ============

  In order to build and execute the LProf, you will need:

  - Trolltech's Qt installed (www.trolltech.com), version 4.3.0 or newer.
    some Linux distros separate Qt into several packages, in which case you'll
    need the core library -dev package as well as the -dev packages for
    qt designer and qt assistant.

    Your Qt must be built with qt3support enabled, though this requirement
    will be dropped later.

  - GNU C compiler gcc or equivalent installed. lprof is primarily tested with gcc
    4.x but will likely build and run if you use gcc 3.4.x.

  - MinGW and msys on a Windows system is required in order to build Qt, VIGRA
    and LProf. Please see the Windows-mingw.txt file for details on setting up
    a build environement using this tool set.

  - Python 1.53 or higher to be able to run SCons on Windows  Linux, Unix and 
    OS/X

  - VIGRA 1.30 or later available here
    http://kogs-www.informatik.uni-hamburg.de/~koethe/vigra/

  - X11 header files are now needed to build LProf on X11 systems. If your
    XVidMode headers are packaged separately you must install them too.

  - libusb

  For all of the above you need both the binary libraries and the header files
  for the library for LProf to build.  On some distributions you will need to
  install "devel" packages to get the needed header files. See "Distro Package
  Names" below for information about specific Linux distros.

  Additionally, in order to profile a scanner or camera, you will
  need a supported profiling target such as an IT8.7 target.  IT8.7 
  targets are available from here:

  http://www.targets.coloraid.de/
  
  Other supported targets include:
  
      Hutch Color Target (tm)
      ColorChecker (tm) 24 patch target
      ColorChecker DC (tm)
      ColorChecker SG (tm)
      EyeOne Scanner 1.4 (tm) target
      DigitaT TargeT 003

  In order to do hardware measured profiling and calibration of your
  displays you will need a supported color meter or spectrophotometer.
  The software at this point has only been tested with a X-Rite EyeOne
  Display LT, X-Rite/Pantone Huey and ColorVision Spyder 2 but should 
  work with the following meters:

     X-Rite EyeOne Display
     X-Rite EyeOne Display Lt
     X-Rite EyeOne Display 2
     X-Rite EyeOne Pro
     X-Rite DTP-92
     X-Rite DTP-94
     ColorVision Spyder 2
     Pantone Huey

  Distro Package Names
  ====================

  The following lists of packages can be installed to satisfy all build dependencies on the
  named distros. The lists are written as a command that you can run in the console to download
  the required packages.

  Ubuntu 7.10 ("Gutsy"):
    sudo apt-get install build-essential cvs scons libqt4-dev qt4-dev-tools libvigraimpex-dev libusb-dev libxxf86vm-dev

  Debian 4.0 ("Etch")
    Debian's version of Qt4 is old for lprof.  To build lprof on Etch you need
    to download recent Qt sources from Trolltech (at least version 4.3.3),
    compile them, and install them.
    You'll also need the following stock distro packages:
        build-essential cvs scons libvigraimpex-dev libusb-dev libxxf86vm-dev libtiff4-dev libpng12-dev
    When you build lprof, make sure to set qt_directory to point to the new Qt.


  Considerations for Building CVS
  ===============================

  CVS does not contain scons-local.  For those building from CVS you must have
  installed scons that is AT LEAST version 0.97 or put a copy of scons-local in
  the root of the LProf source tree. Earlier versions will fail with errors while
  trying to configure QT.  The other option is to get a copy of scons-local
  version 0.97.00 or newer and untar it in the root of the LProf source tree.
  Most other versions are known to fail with errors related to Qt.

  Building and Installing
  =======================

  Starting with version 1.11.0 lprof uses SCons to build and install the
  software and data files.  If you are trying to build CVS you will need to
  install SCons if you do not already have it on your system.  Downloaded tarballs
  will have a known good version of scons-local included.  In addition, SCons
  requires python 1.53 or later to run.  This application package now comes with a
  local copy of scons in the source tarball.  This is to insure that users are
  building with a known good version of SCons.
  
  The LProf scons build now uses the qt4 tool and this needs to have the 
  PKG_CONFIG_PATH environment variable set on Linux/Unix/BSD machine.

  Unpack the tarball or if you are going to use a copy from CVS you must also
  place a known good veriosn copy of scons-local in the root directory of the
  source tree.  In the root directory of the lprof source tree invoke

  $ python scons.py PREFIX=/where/to/install

  to build lprof.  If PREFIX is not specified, it defaults to /usr/local.
  Then (with adequate privileges to write to PREFIX):

  $ python scons.py install

  to install LProf (executables, data, help) to the correct locations
  in PREFIX.  By default this will place the executable files in
  /usr/local/bin and data and help files in /usr/local/share/lprof unless
  you have specified a different PREFIX.  In most cases you will need to
  have root authority to install LProf if the PREFIX is not located in your
  home directory.

  To clean the build directories invoke

  $ python scons.py -c

  which will remove all files created while building the software from
  the build directories.

  To remove LProf from the system, invoke (with adequate privileges):

  $ python scons.py -c install

  which will do everything scons -c does and also remove files installed
  by "scons install" (into PREFIX).

  Running scons will build three executable files which will end up in
  the build directory for whatever platform you are building on.  For
  example on Linux the executables will be created in:

  lprof/build/linux

  The main executable is named lprof, and includes the functionality
  of the four main programs that were built by earlier versions
  (qtmeasurementtool, qtmonitorprofiler, qtscannerprofiler and
  qtprofilechecker) into a single fully integrated piece of software.
  icc2it8 is also part of version 1.11 and is unchanged from earlier
  versions.  The third utility was added after version 1.11.4.x 
  and is for internal use by LProf.

  LProf SCons Command Line Arguments
  ==================================

  There are a number of command line arguments that can be used to
  customize how LProf will build.

  QTDIR

  By default the LProf scons build will search for QT by first
  checking to see if QTDIR is set on the build machine.  If it
  is it will be added to a list of directories where QT is
  commonly installed and it will then check that list of directories
  for a valid QT installation. On some installations QTDIR is either 
  unset or points at the Qt3 installation.  This can be over riden
  by the LProf scons build. 

  To over ride QTDIR during the LProf build use:

   $ python scons.py qt_directory=/some/directory

  The build scripts will check to see if a valid QT installation is
  present in /some/directory before checking any other locations.

  If the build scripts fail to find QT in the above steps it will
  exit with an error message.

  PREFIX

  To specify a non-default installation prefix use:

    $ python scons.py PREFIX=/nondefault/location

  The default installation location is /usr/local

  ccflags

  The default c compiler flags for the LProf build system are -O2 -Wall -pipe

  To change this use:

     $ python scons.py ccflags="-other-valid-flags"

  cxxflags

  This is just like ccflags only it applies to the c++ compiler.

  ldflags

  To set values for LDFLAGS to be passed to the linker us ldflags.
  The default value is '' (empty string).  If you add more than one
  item inclose the whole string in quotes and separate items with
  spaces.

  added_cppflags

  This will allow you to add additional items to the CPPPATH variable
  that is passed to preprocessor.  Use this just like ldflags.

  added_libpath

  This will allow you to add directories to the LIBPATH.  Works just
  like added_cppflags
  
  MacBundlePath
  
  Allows OS/X builds to install the software bundle into a non default location.
  
  MacUniversal
  
  Will make an OS/X Universal build.  Valid values are 0 and 1.  A value of 1
  will cause a Universal build.

  -j

  For those with SMP systems you can force SCons to compile more than
  source file at a time by using the -j parameter.

   $ python scons.py -jn

  Where n is the number of source files to sent to the compiler at
  any given time.  Optimum value for n is likely the number of 
  processors plus one.

 Installing new target reference files
 =====================================

  Starting with version 1.11 LProf now has a dialog to install IT8.7 and 
  other reference files.  The dialog will automatically select the correct
  pick template and when the user later selects that targets refernce file 
  LProf will automatically select the correct picker template.

 Translations
 ============

 LProf's user interface now supports translations to other languages.

 It is currently possible to generate the translation files. To begin translating
 LProf first add the ISO language code for the language you want to translate to
 translations/languages.  Then run createtrans.sh in the root of the source tree.  
 This will cause the translation engine to parse the source code for translatable 
 strings and will create a translations/lprof_<ISO lanaguage code>.ts file for 
 each language listed in the translations/languages file.  At that point you can 
 use any number of tools including Qt's translation tool linguist to add your 
 translations to the translations/lprof_<ISO lanaguage code>.ts file.  Running 
 scons  will generate the qm files that LProf will use when loading its 
 translations. Developers should note that it is not necessary to ship the qm 
 files or store them in CVS; they are be generated as part of the build process.

 Final notes
 ===========

 Don't expect magic. This profiler will build ICC profiles for your
 devices, but is up to the application to use the profiles in order to
 accomplish color management. There are a number of open source
 applications that do know how to use these profiles.  These include
 CinePaint, Scribus, ImageMagick, UFRAW, Krita and starting with 
 version 2.4 GIMP.



