dox/dev_guides/building/wok/wok.md

   1 Using WOK {#occt_dev_guides__building_wok}
   2 =========
   3
   4 @tableofcontents
   5
   6 WOK is a legacy build environment for Open CASCADE Technology.
   7 It is required for generation of header files for classes defined with
   8 CDL ("Cascade Definition Language").
   9 Also tools for generation of project files for other build systems, and OCCT
  10 documentation, are integrated to WOK.
  11
  12 WOK thus is needed in the following situations:
  13 - Building from OCCT sources from Git repository (do not contain generated files)
  14 - Building after some changes made in CDL files
  15
  16 Before installing and using WOK, make sure that you have installed a compiler
  17 (it is assumed that it is Visual Studio on Windows or gcc on Linux and MacOS)
  18 and third-party components required for building OCCT.
  19
  20 @section wok1 Installing WOK
  21
  22   Download the latest version of binary distribution WOK from http://dev.opencascade.org/index.php?q=home/resources
  23
  24 @subsection wok11 Windows
  25
  26   Run the installer. You will be prompted to read and accept the OCCT Public License to proceed:
  27
  28   @image html /dev_guides/building/wok/images/wok_image001.png
  29   @image latex /dev_guides/building/wok/images/wok_image001.png
  30
  31   Click **Next** and proceed with the installation.
  32   At the end of the installation you will be prompted to specify the version and the location of Visual Studio to be used, and the location of third-party libraries:
  33
  34   @image html /dev_guides/building/wok/images/wok_image002.png
  35   @image latex /dev_guides/building/wok/images/wok_image002.png
  36
  37   You can change these settings at any time later. For this click on the item **Customize environment (GUI tool)** in the WOK group in the Windows Start menu.
  38
  39   The shortcuts from this group provide two ways to run WOK:
  40   * In command prompt window using option *WOK TCL shell*.
  41   * In Emacs editor using option *WOK Emacs*. Using Emacs is convenient if you need to work within WOK environment.
  42
  43   By default WOK installer creates a WOK factory with name *LOC* within workshop *dev*. I.e. the WOK path is <i>:LOC:dev</i>.
  44
  45 @subsection wok12 Linux
  46
  47   * Unpack the .tgz archive containing WOK distributive into the installation directory <i>\<WOK_INSTALL_DIR\></i>.
  48
  49   * Perform the following commands assuming that you have unpacked WOK distributive archive into <i>\<WOK_INSTALL_DIR\></i>:
  50   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
  51   cd \<WOK_INSTALL_DIR\>/site
  52   wok_confgui.sh
  53   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  54
  55   Define all necessary paths to third-party products in the dialog window:
  56
  57   @image html /dev_guides/building/wok/images/wok_image003.png
  58   @image latex /dev_guides/building/wok/images/wok_image003.png
  59
  60   * Run the following commands to create WOK LOC factory:
  61   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
  62   cd \<WOK_INSTALL_DIR\>/site
  63   wok_init.sh
  64   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  65
  66   * Your installation procedure is over. To run WOK use one the following commands:
  67   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
  68   cd \<WOK_INSTALL_DIR\>/site
  69   wok_emacs.sh
  70   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  71   or
  72   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
  73   cd \<WOK_INSTALL_DIR\>/site
  74   wok_tclsh.sh
  75   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  76
  77 @subsection wok13 Mac OS X
  78
  79   * Double click on file *wokSetup.dmg* in the Finder. This opens a new window. Drag and drop *wokSetup* folder from this window at the location in the Finder where you want to install WOK, i.e. <i>\<WOK_INSTALL_DIR\></i>.
  80
  81   * Browse to the folder <i>\<WOK_INSTALL_DIR\>/site</i> and double click on *WokConfig*. This opens a window with additional search path settings. Define all necessary paths to third-party products in the dialog window:
  82
  83   @image html /dev_guides/building/wok/images/wok_image004.png
  84   @image latex /dev_guides/building/wok/images/wok_image004.png
  85
  86   * Run the following commands to create WOK LOC factory:
  87   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
  88   cd \<WOK_INSTALL_DIR\>/site
  89   wok_init.sh
  90   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  91
  92   * Your installation procedure is over. To run WOK in Emacs navigate in the Finder to the folder <i>\<WOK_INSTALL_DIR\>/site</i> and double click on *WokEmacs*.
  93
  94
  95 @section wok2 Initialization of Workbench
  96
  97   To start working with OCCT, clone the OCCT Git repository from the server (see http://dev.opencascade.org/index.php?q=home/resources for details) or unpack the source archive.
  98
  99   Then create a WOK workbench (command *wcreate*) setting its Home to the directory, where the repository is created (<i>$CASROOT</i> variable). The workbench should have the same name as that directory.
 100
 101   For example, assuming that OCCT repository has been cloned into *D:/occt* folder:
 102   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
 103   LOC:dev> wcreate occt -DHome=D:/occt
 104   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 105
 106   Note that <i>$CASROOT</i> is equal to *D:/occt* now.
 107
 108   Then you can work with this workbench using normal WOK functionality (*wprocess, umake*, etc.) or use it only for generation of derived sources and project files, and build OCCT with Visual Studio on Windows or *make* command on Linux, as described below.
 109
 110 @section wok3 Generation of building projects
 111
 112   Use command *wgenproj* in WOK to generate derived headers, source and building projects files:
 113   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
 114   LOC:dev> wokcd occt
 115   LOC:dev:occt> wgenproj [ -target=<TARGET> ] [ -no_wprocess ]
 116   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 117 TARGET:
 118   * *vc8* -- Visual Studio 2005;
 119   * *vc9* -- Visual Studio 2008;
 120   * *vc10* -- Visual Studio 2010;
 121   * *vc11* -- Visual Studio 2012;
 122   * *cbp* -- CodeBlocks;
 123   * *cmake* -- CMake;
 124   * *amk* -- AutoMake;
 125   * *xcd* -- Xcode;
 126   * <i>-no_wprocess</i> option skips generation of derived headers and source files.
 127
 128 Note that this command takes several minutes to complete at the first call.
 129
 130 Re-execute this step to generate derived headers, source and building projects files if some CDL files in OCCT have been modified (either by you directly, or due to updates in the repository). Note that in some cases WOK may fail to update correctly; in such case remove sub-directories *drv* and <i>.adm</i> and repeat the command.
 131
 132 To regenerate derived headers and source files without regeneration of projects use command:
 133   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
 134   LOC:dev> wokcd occt
 135   LOC:dev:occt> wprocess -DGroups=Src,Xcpp
 136   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 137 The generated building project has been placed into <i>$CASROOT/adm</i> folder:
 138   * for vc8 -- <i>$CASROOT/adm/msvc/vc8</i>;
 139   * for vc9 -- <i>$CASROOT/adm/msvc/vc9</i>;
 140   * for vc10 -- <i>$CASROOT/adm/msvc/vc10</i>;
 141   * for vc11 -- <i>$CASROOT/adm/msvc/vc11</i>;
 142   * for cbp -- <i>$CASROOT/adm/\<OS\>/cbp</i>;
 143   * for cmake -- <i>$CASROOT/adm/cmake</i>;
 144   * for amk -- <i>$CASROOT/adm/lin/amk</i>;
 145   * xcd -- <i>$CASROOT/adm/\<OS\>/xcd</i>
 146
 147 @section wok4  Generation of documentation
 148
 149   Use command *wgendoc* in WOK to generate reference documentation:
 150   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
 151   :LOC:dev> wokcd occt
 152   :LOC:dev:occt> wgendoc
 153   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 154 The following options can be used:
 155   * <i>-wb=\<workbench name\></i> -- the name of OCCT workbench (the current one by default);
 156   * <i>-m=\<list of modules\></i> -- the list of modules that will be contained in the documentation;
 157   * <i>-outdir=\<path\></i> -- the output directory for the documentation;
 158   * <i>-chm</i> -- the option to generate CHM file;
 159   * <i>-hhc=\<path\></i> -- the path to HTML Help Compiler *hhc.exe* or equivalent;
 160   * <i>-qthelp=\<path\></i> -- the option to generate Qt Help file, where <i>\<path\></i> is the required path to *qthelpgenerator* executable;
 161   * <i>-doxygen=\<path\></i> -- the path to Doxygen executable;
 162   * <i>-dot=\<path\></i> -- the path to GraphViz dot executable.