=============================================================
# ZeosDBO
##  C++Builder Packages Installation Manual


  By
    Marcelo Augusto Cicogna
    HydroByte Software

=============================================================
## Goals
  - New C++Builder packages.
  - Reorganize C++ compiled files derived from ZeosDBO's
    Object Pascal source.
  - Allow more than one version or build to coexist on
    Windows.
  - Allow our project to be easily setup to use ZeosDBO,
    focused in checking items in
    "Project > Options > Packages" list.

  Tested with ZeosDBO 7.2.6 Revision 5971 from SVN.

-------------------------------------------------------------
## Notation
  * [Name]: IDE name or localization tag.
  * {Path}: Shortcut for paths names.
  
  Note: here {Path} is not like IDE's macros $(Path).
  
  See APPENDIX A for IDE Names and Localization.

-------------------------------------------------------------
## Pre Conditions

  a) If compiling from new source code, remove ZeosDBO
     package from Installed Packages before start.
  b) Clean target Bpl, Lib and Include folders.

-------------------------------------------------------------
## 1. C++Builder Version, Platform and Config

  a) Unpack ZeosDBO, or get a SVN version, in a folder of
     your choice.
     Let's call it "{ZeosDBOFolder}".
     For example:
       "C:\MyComponents\ZeosDBO"

  b) Choose your C++Builder version in ZeosDBO "\packages"
     folder. For example:
       "{ZeosDBOFolder}\packages\CBuilder2009".
     Let's call this entire path of {CBZeosPath}.

  c) For C++Builder 2009.
     {Platform} exists just in this manual, not in the IDE.
     {Platform} is always equals to "Win32".
     Check if there is your Platform and Config. You may have 
     to create the paths:
       "{CBZeosPath}\{Platform}\{Config}"
     For example:
       "C:\MyComponents\ZeosDBO\packages\CBuilder2009\Win32\Release"
       "C:\MyComponents\ZeosDBO\packages\CBuilder2009\Win32\Debug"

     By default, C++Builder ZeosDBO packages are set to
     Platform = Win32 and Config = Release.    

-------------------------------------------------------------
## 2. Environment Setup

  a) Open your IDE.

  b) Access IDE's "Environment Variables".

  c) Under "System variables" click "Add Override"
     and add "{CBZeosPath}\Win32\{Config}\Bpl;" to "Path".
     For example:
       "C:\MyComponents\ZeosDBO\packages\CBuilder2009\Win32\Release\Bpl"
     See Troubleshoot 6.b.

  d) Under "User overrides" create "ZEOSDBO" variable with
     value equals to {CBZeosPath} (see Step 1.b).

  e) Under IDE's [Include Path] proceed:
       Add 
         "$(ZEOSDBO)\Win32\Release\Include"
       
     Under IDE's [Library Path] proceed:
       Add
         "$(ZEOSDBO)\Win32\Release\Lib"
     See Troubleshoot 6.c.
     
  f) Access Windows' "Environment Variables".
     In "User variables for <user>" add
       "{CBZeosPath}\Win32\{Config}\Bpl;" to "Path".
     For example:
       "C:\MyComponents\ZeosDBO\packages\CBuilder2009\Win32\Release\Bpl"
     See Troubleshoot 6.f.

  Note: you can repeat steps c) and e) for multi-config 
    options that you may use in your projects.

-------------------------------------------------------------
## 3. Install (Win32)

  a) Open "{CBZeosPath}\ZeosDbo.groupproj" group project.

  b) Build all projects, except "ZComponentDesign{XXX}.bpl".
     Note: don't Make all. Build them.
     See Troubleshoot 6.c and 6.e.

  c) Right click on "ZComponentDesign{XXX}.bpl" project, in
     Project Manager, and choose "Install". If the
     installation succeeds, you will receive a dialog
     confirmation about the ZeosDBO Installed Components.     
     See Troubleshoot 6.b.

-------------------------------------------------------------
## 4. Your Project

  a) It is important to check one option in your project that
     will use ZeosDBO.
     Under [C++ Linker], set or check these option:
       "Link with Dynamic RTL" = true;
       "Link with the Delphi Runtime Library" = false

     In other words, this option must be equal to those found
     in ZeosDBO Packages, at IDE's [C++ Linker].
     By default, C++Builder ZeosDBO packages set these
     options to true and false, respectively.     
     See Troubleshoot 6.a.

-------------------------------------------------------------
## 5. Deploy

  a) If you are using dynamic build packages, deploy the
     "Z*{XXX}.bpl" files, except "ZComponentDesign{XXX}.bpl", 
     where "{XXX}" relates to CBuilder Compiler version, with 
     your application.
     The packages "Z*{XXX}.bpl" are located in folder:
       "{CBZeosPath}\{Platform}\{Config}\Bpl".

-------------------------------------------------------------
## 6. Troubleshoot

  a) Project <Prj.exe> raised exception class <$Address> with
     message 'access violation at <0xAddress>: read of
     address <0xAddress>
     - See Step 4 about [C++ Linker] and "Link with Dynamic RTL"
       Make sure your project has the same option as ZeosDBO
       Packages (by default, Dynamic RTL is set to false).

  b) Installing "ZComponentDesign{XXX}.bpl" raises errors about
     ZCore.bpl could not be found.
     - Check if the "{CBZeosPath}\{Platform}\{Config}\Bpl;" was
       included into "Path" as determined at Step 2.c.

  c) Errors complaining about *.dcu missing files.
     - Check Step 2.e.
     - Check Step 3.b.

  d) ilink64 errors complaining about unresolved external *.o files.
     - Remove Z*.bpi from Requires list (Project Manager treeview)
       and Add Reference... again.

  e) At compiling start, dialog asking to remove units.
     Mark "View details" and check which package name is shown as
     "required" in the end of de list. 
     - Uncheck Zeos from installed packages.
     - if error persists, check and clean BPL files from
       Embarcadero "Public Documents" directory.
         C:\Users\Public\Documents\Embarcadero\Studio\19.0\BPL
     - If error persists, restart the IDE.
     
  f) Errors complaining about Z*.bpl missing files when running
     your app.
     - If inside IDE, check Path in Step 2.c.
     - If outside IDE, check Path in Step 2.f.

-------------------------------------------------------------
## 7. Clean Up

  ZeosDBO packages for C++Builder 2009 or up have some
  clean up tasks scheduled to post build operation.
  See IDE's Post-Build at [Build Events].

-------------------------------------------------------------
## 8. Debug

  If you want to debug ZeosDBO source code, take these steps:

  a) Setup your IDE Environment.
     See Steps 2.c and 2.e.
     Under "User overrides" create "ZEOSDBOSOURCE" variable
     with value equals to:
       "{ZeosDBOFolder}\src"

  b) Open "{CBZeosPath}\ZeosDbo.groupproj" group project and
     change the "Build Configuration" to "Debug".
     Build all projects.
     See also Setp 1.c.

  c) Under [Debugger], add items to "Source path":
      $(ZEOSDBOSOURCE)
      $(ZEOSDBOSOURCE)\core
      $(ZEOSDBOSOURCE)\plain
      $(ZEOSDBOSOURCE)\parsesql
      $(ZEOSDBOSOURCE)\dbc
      $(ZEOSDBOSOURCE)\component

  d) Into your project, with Debug configuration, do:
     - Under [C++ Linker] set
       "Link with Dynamic RTL" to false.
     - Under [Runtime Packages] set
       "Build/Link with runtime packages" to false.


=============================================================
## APPENDIX

-------------------------------------------------------------
## A. IDE Names and Localization

  - CBuilder2009

    [Include Path]:
    "Tools > Options > Env. Options > C++ Options > Paths and Directories"

    [Libray Path]:
    "Tools > Options > Env. Options > C++ Options > Paths and Directories"

    [C++ Linker]
    "Project > Options > C++ Linker"

    [Build Events]
    "Project > Options > Build Events"

    [Debugger]
    "Project > Options > Debugger"

    [Runtime Packages]
    "Project > Options > Packages"