From ba06f8bbee309a4905b95bc2626574ea4b9c13d6 Mon Sep 17 00:00:00 2001 From: omy Date: Thu, 10 Apr 2014 18:23:18 +0400 Subject: [PATCH] 0024722: Move functionality of WOK command wgendoc to OCCT tool gendoc Command gendoc improved to: - generate Reference Manual documentation (OCCT classes reference) with option -refman; option -overview can be used for generation of overview documentation; - generate PDF documents for all User Guides automatically (for files listed in FILES_PDF.txt); - check availability of third-party tools (Doxygen, Inkscape etc.) and properly report warnings and errors. - use templates of configuration files for third-party tools instead of their generation. These template files are located in dox/resources folder Tcl scripts are moved from dox folder to adm. Doxygen warnings are eliminated. Moved all auxilary functions to occaux.tcl. Fixed Reference manual generation on *nix platform. Fixed PDF generation on *nix platforms. --- adm/gendoc.tcl | 825 ++++++++++++++++ adm/occaux.tcl | 897 ++++++++++++++++++ adm/start.tcl | 8 + dox/{FILES.txt => FILES_HTML.txt} | 0 dox/FILES_PDF.txt | 32 + .../building/3rdparty/3rdparty_linux.md | 2 +- .../building/3rdparty/3rdparty_osx.md | 2 +- .../building/3rdparty/3rdparty_windows.md | 2 +- dox/dev_guides/building/automake.md | 6 +- dox/dev_guides/building/building.md | 23 +- dox/dev_guides/building/cmake/cmake.md | 6 +- dox/dev_guides/building/code_blocks.md | 6 +- dox/dev_guides/building/msvc.md | 6 +- dox/dev_guides/building/wok/wok.md | 6 +- dox/dev_guides/building/xcode.md | 6 +- dox/dev_guides/cdl/cdl.md | 2 +- dox/dev_guides/contribution/coding_rules.md | 6 +- .../contribution_workflow.md | 2 +- dox/dev_guides/debug/debug.md | 4 +- dox/dev_guides/dev_guides.md | 18 +- dox/dev_guides/documentation/documentation.md | 50 +- dox/dev_guides/git_guide/git_guide.md | 4 +- dox/dev_guides/tests/tests.md | 8 +- dox/dev_guides/wok/wok.md | 747 +++++++-------- dox/license.md | 521 ++++++++++ dox/occdoc.tcl | 875 ----------------- dox/overview/Overview.md | 27 +- dox/overview/overview.md | 616 ++++++++++++ dox/resources/index.html | 9 + dox/resources/occt_pdf_template.tex | 145 +++ dox/resources/occt_rm.doxyfile | 46 + dox/resources/occt_ug_html.doxyfile | 60 ++ dox/resources/occt_ug_pdf.doxyfile | 53 ++ dox/start.tcl | 7 - dox/tutorial/images/tutorial_image003.svg | 61 +- dox/tutorial/tutorial.md | 4 +- dox/user_guides/brep_wp/brep_wp.md | 2 +- dox/user_guides/draw_test_harness.md | 234 ++--- .../foundation_classes/foundation_classes.md | 34 +- dox/user_guides/iges/iges.md | 284 +++--- .../modeling_algos/modeling_algos.md | 2 +- .../modeling_data/modeling_data.md | 8 +- dox/user_guides/ocaf/ocaf.md | 22 +- .../ocaf_functionmechanism_wp.md | 16 +- dox/user_guides/ocaf_tree_wp/ocaf_tree_wp.md | 2 +- dox/user_guides/ocaf_wp/ocaf_wp.md | 20 +- .../shape_healing/shape_healing.md | 6 +- dox/user_guides/step/step.md | 432 ++++----- dox/user_guides/tobj/tobj.md | 2 +- dox/user_guides/user_guides.md | 32 +- .../visualization/visualization.md | 20 +- dox/user_guides/voxels_wp/voxels_wp.md | 6 +- dox/user_guides/xde/xde.md | 2 +- gendoc.sh => gendoc | 2 +- gendoc.bat | 2 +- 55 files changed, 4297 insertions(+), 1923 deletions(-) create mode 100644 adm/gendoc.tcl create mode 100644 adm/occaux.tcl create mode 100644 adm/start.tcl rename dox/{FILES.txt => FILES_HTML.txt} (100%) create mode 100644 dox/FILES_PDF.txt create mode 100644 dox/license.md delete mode 100644 dox/occdoc.tcl create mode 100644 dox/overview/overview.md create mode 100644 dox/resources/index.html create mode 100644 dox/resources/occt_pdf_template.tex create mode 100644 dox/resources/occt_rm.doxyfile create mode 100644 dox/resources/occt_ug_html.doxyfile create mode 100644 dox/resources/occt_ug_pdf.doxyfile delete mode 100755 dox/start.tcl rename gendoc.sh => gendoc (92%) mode change 100755 => 100644 diff --git a/adm/gendoc.tcl b/adm/gendoc.tcl new file mode 100644 index 0000000000..2242696f96 --- /dev/null +++ b/adm/gendoc.tcl @@ -0,0 +1,825 @@ +# ======================================================================= +# Created on: 2014-03-21 +# Created by: OMY +# Copyright (c) 1996-1999 Matra Datavision +# Copyright (c) 1999-2014 OPEN CASCADE SAS +# +# This file is part of Open CASCADE Technology software library. +# +# This library is free software; you can redistribute it and/or modify it under +# the terms of the GNU Lesser General Public License version 2.1 as published +# by the Free Software Foundation, with special exception defined in the file +# OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT +# distribution for complete text of the license and disclaimer of any warranty. +# +# Alternatively, this file may be used under the terms of Open CASCADE +# commercial license or contractual agreement. +# +# Brief: This script compiles OCCT documents from *.md files to HTML pages +# ======================================================================= + +# ====================================== +# Common functions +# ====================================== + +# Prints help message +proc OCCDoc_PrintHelpMessage {} { + puts "\nUsage: gendoc \[-h\] {-refman|-overview} \[-html|-pdf|-chm\] \[-m=|-ug=\] \[-v\] \[-s=\] \[-mathjax=\]" + puts "" + puts "Options are:" + puts "" + puts "choice of documentation to be generated:" + puts " -overview : To generate Overview and User Guides" + puts " (cannot be used with -refman)" + puts " -refman : To generate class Reference Manual" + puts " (cannot be used with -overview)" + puts "" + puts "choice of output format:" + puts " -html : To generate HTML files" + puts " (default, cannot be used with -pdf or -chm)" + puts " -pdf : To generate PDF files" + puts " (cannot be used with -refman, -html, or -chm)" + puts " -chm : To generate CHM files" + puts " (cannot be used with -html or -pdf)" + puts "" + puts "additional options:" + puts " -m= : List of OCCT modules (separated with comma)," + puts " for generation of Reference Manual" + puts " -ug= : List of MarkDown documents (separated with comma)," + puts " to use for generation of Overview / User Guides" + puts " -mathjax= : To use local or alternative copy of MathJax" + puts " -s= : Specifies the Search mode of HTML documents" + puts " Can be: none | local | server | external" + puts " -h : Prints this help message" + puts " -v : Enables more verbose output" +} + +# A command for User Documentation compilation +proc gendoc {args} { + + # Parameters + set DOC_TYPE "REFMAN" + set GEN_MODE "HTML_ONLY" + set DOCFILES {} + set MODULES {} + set DOCLABEL "" + set VERB_MODE "NO" + set SEARCH_MODE "none" + set MATHJAX_LOCATION "http://cdn.mathjax.org/mathjax/latest" + set mathjax_js_name "MathJax.js" + set DOCTYPE_COMBO_FLAG 0 + set GENMODE_COMBO_FLAG 0 + set GENERATE_PRODUCTS_REFMAN "NO" + + global available_docfiles; # The full list of md files for HTML or CHM generation + global available_pdf; # The full list of md files for PDF generation + global tcl_platform + global args_names + global args_values + global env + + # Load list of docfiles + if { [OCCDoc_LoadFilesList] != 0 } { + puts "Error: File FILES_HTML.txt or FILES_PDF.txt was not found on this computer.\nAborting..." + return -1 + } + + # Parse CL arguments + if {[OCCDoc_ParseArguments $args] == 1} { + return -1 + } + + # Print help message if no arguments provided + if {[llength $args_names] == 0} { + OCCDoc_PrintHelpMessage + return 0 + } + + foreach arg_n $args_names { + if {$arg_n == "h"} { + OCCDoc_PrintHelpMessage + return 0 + } elseif {$arg_n == "html"} { + if { ([ lsearch $args_names "refman" ] == -1) && + ([ lsearch $args_names "overview" ] == -1) } { + puts "Warning: Please specify -refman or -overview argument." + return -1 + } + if { [ lsearch $args_names "refman" ] != -1 } { + continue + } + if { $GENMODE_COMBO_FLAG != 1 } { + set GEN_MODE "HTML_ONLY" + set GENMODE_COMBO_FLAG 1 + } else { + puts "Error: Options -html, -pdf and -chm can not be combined." + return -1 + } + } elseif {$arg_n == "chm"} { + if { ([ lsearch $args_names "refman" ] == -1) && + ([ lsearch $args_names "overview" ] == -1) } { + puts "Warning: Please specify -refman or -overview argument." + return -1 + } + if { [ lsearch $args_names "refman" ] != -1 } { + continue + } + if { $GENMODE_COMBO_FLAG != 1 } { + set GEN_MODE "CHM_ONLY" + set GENMODE_COMBO_FLAG 1 + } else { + puts "Error: Options -html, -pdf and -chm cannot be combined." + return -1 + } + } elseif {$arg_n == "pdf"} { + if { ([ lsearch $args_names "refman" ] == -1) && + ([ lsearch $args_names "overview" ] == -1) } { + puts "Warning: Please specify -refman or -overview argument." + return -1 + } + if { [ lsearch $args_names "refman" ] != -1 } { + continue + } + if { $GENMODE_COMBO_FLAG != 1 } { + set GEN_MODE "PDF_ONLY" + set GENMODE_COMBO_FLAG 1 + } else { + puts "Error: Options -html, -pdf and -chm cannot be combined." + return -1 + } + } elseif {$arg_n == "overview"} { + if { $DOCTYPE_COMBO_FLAG != 1 } { + set DOC_TYPE "OVERVIEW" + set DOCTYPE_COMBO_FLAG 1 + } else { + puts "Error: Options -refman and -overview cannot be combined." + return -1 + } + + # Print ignored options + if { [ lsearch $args_names "m" ] != -1 } { + puts "\nInfo: The following options will be ignored: \n" + puts " * -m" + } + puts "" + } elseif {$arg_n == "refman"} { + if { $DOCTYPE_COMBO_FLAG != 1 } { + set DOC_TYPE "REFMAN" + set DOCTYPE_COMBO_FLAG 1 + if { [file exists [pwd]/src/VAS/Products.tcl] } { + set GENERATE_PRODUCTS_REFMAN "YES" + } + } else { + puts "Error: Options -refman and -overview cannot be combined." + return -1 + } + # Print ignored options + if { ([ lsearch $args_names "pdf" ] != -1) || + ([ lsearch $args_names "chm" ] != -1) || + ([ lsearch $args_names "ug" ] != -1) } { + puts "\nInfo: The following options will be ignored: \n" + if { [ lsearch $args_names "pdf" ] != -1 } { + puts " * -pdf" + } + if { [ lsearch $args_names "chm" ] != -1 } { + puts " * -chm" + } + if { [ lsearch $args_names "ug" ] != -1 } { + puts " * -ug" + } + puts "" + } + + if { $GENERATE_PRODUCTS_REFMAN == "YES" } { + if { [ lsearch $args_names "m" ] == -1 } { + puts "\nError: Cannot generate Reference Manual for the whole set of OCC Products." + puts "Aborting..." + return -1 + } + } + } elseif {$arg_n == "v"} { + set VERB_MODE "YES" + } elseif {$arg_n == "ug"} { + if { ([ lsearch $args_names "refman" ] != -1) } { + continue + } + if {$args_values(ug) != "NULL"} { + set DOCFILES $args_values(ug) + } else { + puts "Error in argument ug." + return -1 + } + # Check if all chosen docfiles are correct + foreach docfile $DOCFILES { + if { [ lsearch $args_names "pdf" ] == -1 } { + # Check to generate HTMLs + if { [lsearch $available_docfiles $docfile] == -1 } { + puts "Error: File \"$docfile\" is not presented in the list of available docfiles." + puts " Please specify the correct docfile name." + return -1 + } + } else { + # Check to generate PDFs + if { [lsearch $available_pdf $docfile] == -1 } { + puts "Error: File \"$docfile\" is not presented in the list of generic PDFs." + puts " Please specify the correct pdf name." + return -1 + } + } + } + } elseif {$arg_n == "m"} { + if { [ lsearch $args_names "overview" ] != -1 } { + continue + } + if {$args_values(m) != "NULL"} { + set MODULES $args_values(m) + } else { + puts "Error in argument m." + return -1 + } + } elseif {$arg_n == "s"} { + if { [ lsearch $args_names "pdf" ] != -1 } { + continue + } + if {$args_values(s) != "NULL"} { + set SEARCH_MODE $args_values(s) + } else { + puts "Error in argument s." + return -1 + } + } elseif {$arg_n == "mathjax"} { + if { [ lsearch $args_names "pdf" ] != -1 } { + set possible_mathjax_loc $args_values(mathjax) + if {[file exist [file join $possible_mathjax_loc $mathjax_js_name]]} { + set MATHJAX_LOCATION $args_values(mathjax) + puts "$MATHJAX_LOCATION" + } else { + puts "Warning: $mathjax_js_name is not found in $possible_mathjax_loc." + puts " MathJax will be used from $MATHJAX_LOCATION" + } + } else { + puts "Warning: MathJax is not used with pdf and will be ignored." + } + } else { + puts "\nWrong argument: $arg_n" + OCCDoc_PrintHelpMessage + return -1 + } + } + + # Check the existence of the necessary tools + set DOXYGEN_PATH "" + set GRAPHVIZ_PATH "" + set INKSCAPE_PATH "" + set PDFLATEX_PATH "" + set HHC_PATH "" + + OCCDoc_DetectNecessarySoftware $DOXYGEN_PATH $GRAPHVIZ_PATH $INKSCAPE_PATH $HHC_PATH $PDFLATEX_PATH + + if {$DOXYGEN_PATH == ""} { + puts " Aborting..." + return -1 + } + + if {"$::tcl_platform(platform)" == "windows"} { + if { ($GEN_MODE == "CHM_ONLY") && ($HHC_PATH == "") } { + puts " Aborting..." + return -1 + } + } + + if { ($PDFLATEX_PATH == "") && ($GEN_MODE == "PDF_ONLY") } { + puts " Aborting..." + return -1 + } + + # If we do not specify list for docfiles with -m argument, + # we assume that we have to generate all docfiles + if { [llength $DOCFILES] == 0 } { + if { $GEN_MODE != "PDF_ONLY" } { + set DOCFILES $available_docfiles + } else { + set DOCFILES $available_pdf + } + } + + puts "" + + # Clean logfiles + set OUTDIR [OCCDoc_GetRootDir]/doc/ + set DOXYLOG $OUTDIR/doxygen_warnings_and_errors.log + set PDFLOG $OUTDIR/pdflatex_warnings_and_errors.log + + file delete -force $PDFLOG + file delete -force $DOXYLOG + + # Start main activities + if { $GEN_MODE != "PDF_ONLY" } { + OCCDoc_Main $DOC_TYPE $DOCFILES $MODULES $GEN_MODE $VERB_MODE $SEARCH_MODE $MATHJAX_LOCATION $GENERATE_PRODUCTS_REFMAN $DOXYGEN_PATH $GRAPHVIZ_PATH $INKSCAPE_PATH $HHC_PATH + } else { + puts "Generating OCCT User Guides in PDF format...\n" + foreach pdf $DOCFILES { + + puts "Info: Processing file $pdf\n" + + # Some values are hardcoded because they are related only to PDF generation + OCCDoc_Main "OVERVIEW" [list $pdf] {} "PDF_ONLY" $VERB_MODE "none" $MATHJAX_LOCATION "NO" $DOXYGEN_PATH $GRAPHVIZ_PATH $INKSCAPE_PATH $HHC_PATH + } + puts "[clock format [clock seconds] -format {%Y-%m-%d %H:%M}] Generation completed." + puts "\nPDF files are generated in \n[file normalize [OCCDoc_GetRootDir]/doc/pdf]" + } +} + +# Main procedure for documents compilation +proc OCCDoc_Main {docType {docfiles {}} {modules {}} generatorMode verboseMode searchMode mathjaxLocation generateProductsRefman DOXYGEN_PATH GRAPHVIZ_PATH INKSCAPE_PATH HHC_PATH} { + + global available_docfiles + global available_pdf + + set PRODPATH "" + if { [string compare -nocase $generateProductsRefman "YES"] == 0 } { + set PRODPATH [pwd] + } + + set ROOTDIR [OCCDoc_GetRootDir $PRODPATH] + set INDIR [OCCDoc_GetDoxDir] + set OUTDIR $ROOTDIR/doc + set PDFDIR $OUTDIR/pdf + set UGDIR $PDFDIR/user_guides + set DGDIR $PDFDIR/dev_guides + set TAGFILEDIR $OUTDIR/refman + set HTMLDIR $OUTDIR/overview/html + set LATEXDIR $OUTDIR/overview/latex + set DOXYFILE $OUTDIR/OCCT.cfg + + # Create or cleanup the output folders + if { [string compare -nocase $generateProductsRefman "YES"] != 0 } { + if { ![file exists $OUTDIR] } { + file mkdir $OUTDIR + } + if { ![file exists $HTMLDIR] } { + file mkdir $HTMLDIR + } + if { ![file exists $PDFDIR] } { + file mkdir $PDFDIR + } + if { ![file exists $UGDIR] } { + file mkdir $UGDIR + } + if { ![file exists $DGDIR] } { + file mkdir $DGDIR + } + if { [file exists $LATEXDIR] } { + file delete -force $LATEXDIR + } + file mkdir $LATEXDIR + } + if { $docType == "REFMAN" } { + if { ![file exists $TAGFILEDIR] } { + file mkdir $TAGFILEDIR + } + } + + # is MathJax HLink? + set mathjax_relative_location $mathjaxLocation + if { [file isdirectory "$mathjaxLocation"] } { + if { $generatorMode == "HTML_ONLY" } { + # related path + set mathjax_relative_location [OCCDoc_GetRelPath $HTMLDIR $mathjaxLocation] + } elseif { $generatorMode == "CHM_ONLY" } { + # absolute path + set mathjax_relative_location [file normalize $mathjaxLocation] + } + } + + if { $generateProductsRefman == "YES" } { + set DOCDIR "$OUTDIR/refman" + puts "\nGenerating OCC Products Reference Manual\n" + } else { + if { $docType == "REFMAN"} { + set DOCDIR "$OUTDIR/refman" + puts "\nGenerating Open CASCADE Reference Manual\n" + } elseif { $docType == "OVERVIEW" } { + set DOCDIR "$OUTDIR/overview" + set FORMAT "" + if { ($generatorMode == "HTML_ONLY") || ($generatorMode == "CHM_ONLY") } { + if { $generatorMode == "HTML_ONLY" } { + set FORMAT " in HTML format..." + } elseif { $generatorMode == "CHM_ONLY" } { + set FORMAT " in CHM format..." + } + puts "Generating OCCT User Guides$FORMAT\n" + } + } else { + puts "Error: Invalid documentation type: $docType. Can not process." + return -1 + } + } + + # Generate Doxyfile + puts "[clock format [clock seconds] -format {%Y-%m-%d %H:%M}] Generating Doxyfile..." + + if { [OCCDoc_MakeDoxyfile $docType $DOCDIR $TAGFILEDIR $DOXYFILE $generatorMode $docfiles $modules $verboseMode $searchMode $HHC_PATH $mathjax_relative_location $GRAPHVIZ_PATH $PRODPATH] == -1 } { + return -1 + } + + # Run doxygen tool + set starttimestamp [clock format [clock seconds] -format {%Y-%m-%d %H:%M}] + + if { ($generatorMode == "HTML_ONLY") || ($docType == "REFMAN") } { + puts "$starttimestamp Generating HTML files..." + + # Copy index file to provide fast access to HTML documentation + file copy -force $INDIR/resources/index.html $DOCDIR/index.html + } elseif { $generatorMode == "CHM_ONLY" } { + puts "$starttimestamp Generating CHM file..." + } elseif { $generatorMode == "PDF_ONLY" } { + puts "$starttimestamp Generating PDF file..." + } + + set DOXYLOG $OUTDIR/doxygen_warnings_and_errors.log + set RESULT [catch {exec $DOXYGEN_PATH $DOXYFILE >> $OUTDIR/doxygen_out.log} DOX_ERROR] + if {$RESULT != 0} { + set NbErrors [regexp -all -line {^\s*[^\s]+} $DOX_ERROR] + if {$NbErrors > 0} { + puts "\nWarning: Doxygen reported $NbErrors messages." + puts "See log in $DOXYLOG\n" + set DOX_ERROR_FILE [open $DOXYLOG "a"] + if {$generatorMode == "PDF_ONLY"} { + puts $DOX_ERROR_FILE "\n====================================================" + puts $DOX_ERROR_FILE "Logfile for $docfiles" + puts $DOX_ERROR_FILE "====================================================\n" + } + puts $DOX_ERROR_FILE $DOX_ERROR + close $DOX_ERROR_FILE + } + } + + # Close the Doxygen application + after 300 + + # Start Post Processing + set curtime [clock format [clock seconds] -format {%Y-%m-%d %H:%M}] + if { $docType == "REFMAN" } { + # Post Process generated HTML pages and draw dependency graphs + if {[OCCDoc_PostProcessor $DOCDIR] == 0} { + puts "$curtime Generation completed." + puts "\nInfo: doxygen log file is located in:" + puts "$OUTDIR/doxygen_out.log." + puts "\nReference Manual is generated in \n$DOCDIR" + } + } elseif { $docType == "OVERVIEW" } { + # Start PDF generation routine + if { $generatorMode == "PDF_ONLY" } { + set OS $::tcl_platform(platform) + if { $OS == "unix" } { + set PREFIX ".sh" + } elseif { $OS == "windows" } { + set PREFIX ".bat" + } + + # Prepare a list of TeX files, generated by Doxygen + cd $LATEXDIR + + set TEXFILES [glob $LATEXDIR -type f -directory $LATEXDIR -tails "*.tex" ] + foreach path $TEXFILES { + if { [string compare -nocase $path $LATEXDIR] == 0 } { + set DEL_IDX [lsearch $TEXFILES $path] + if { $DEL_IDX != -1 } { + set TEXFILES [lreplace $TEXFILES $DEL_IDX $DEL_IDX] + } + } + } + set TEXFILES [string map [list refman.tex ""] $TEXFILES] + if {$verboseMode == "YES"} { + puts "Info: Preprocessing generated TeX files..." + } + OCCDoc_ProcessTex $TEXFILES $LATEXDIR $verboseMode + + if {$verboseMode == "YES"} { + puts "Info: Converting SVG images to PNG format..." + } + + if { $INKSCAPE_PATH != "" } { + OCCDoc_ProcessSvg $LATEXDIR $verboseMode + } else { + puts "Warning: SVG images will be lost in PDF documents." + } + + if {$verboseMode == "YES"} { + puts "Info: Generating PDF file from TeX files..." + } + foreach TEX $TEXFILES { + # Rewrite existing REFMAN.tex file... + set TEX [lindex [split $TEX "."] 0] + + if {$verboseMode == "YES"} { + puts "Info: Generating PDF file from $TEX..." + } + + OCCDoc_MakeRefmanTex $TEX $LATEXDIR $verboseMode $available_pdf + + if {"$::tcl_platform(platform)" == "windows"} { + set is_win "yes" + } else { + set is_win "no" + } + if {$verboseMode == "YES"} { + # ...and use it to generate PDF from TeX... + if {$is_win == "yes"} { + puts "Info: Executing $LATEXDIR/make.bat..." + } else { + puts "Info: Executing $LATEXDIR/Makefile..." + } + } + set PDFLOG $OUTDIR/pdflatex_warnings_and_errors.log + + if {"$is_win" == "yes"} { + set RESULT [catch {eval exec [auto_execok $LATEXDIR/make.bat] >> "$OUTDIR/pdflatex_out.log"} LaTeX_ERROR] + } else { + set RESULT [catch {eval exec "make -f $LATEXDIR/Makefile" >> "$OUTDIR/pdflatex_out.log"} LaTeX_ERROR] + + # Small workaround for *nix stations + set prev_loc [pwd] + cd $LATEXDIR + set RESULT [catch {eval exec "pdflatex refman.tex" >> "$OUTDIR/pdflatex_out.log"} LaTeX_ERROR] + cd $prev_loc + } + + if {$RESULT != 0} { + set NbErrors [regexp -all -line {^\s*[^\s]+} $LaTeX_ERROR] + if {$NbErrors > 0} { + puts "\nWarning: PDFLaTeX reported $NbErrors messages.\nSee log in $PDFLOG\n" + set LaTeX_ERROR_FILE [open $PDFLOG "a"] + puts $LaTeX_ERROR_FILE "\n====================================================" + puts $LaTeX_ERROR_FILE "Logfile of file $TEX:" + puts $LaTeX_ERROR_FILE "====================================================\n" + puts $LaTeX_ERROR_FILE $LaTeX_ERROR + close $LaTeX_ERROR_FILE + } + } + + # ...and place it to the specific folder + if {![file exists "$LATEXDIR/refman.pdf"]} { + puts "Fatal: PDFLaTeX failed to create output file, stopping!" + return -1 + } + + set destFolder $PDFDIR + set parsed_string [split $TEX "_"] + if { [lsearch $parsed_string "tutorial"] != -1 } { + set TEX [string map [list occt__ occt_] $TEX] + set destFolder $PDFDIR + } elseif { [lsearch $parsed_string "user"] != -1 } { + set TEX [string map [list user_guides__ ""] $TEX] + set destFolder $UGDIR + } elseif { [lsearch $parsed_string "dev"] != -1 } { + set TEX [string map [list dev_guides__ ""] $TEX] + set destFolder $DGDIR + } + file rename -force $LATEXDIR/refman.pdf "$destFolder/$TEX.pdf" + + } + } elseif { $generatorMode == "CHM_ONLY" } { + file rename $OUTDIR/overview.chm $OUTDIR/occt_overview.chm + } + cd $INDIR + + if { $generatorMode == "HTML_ONLY" } { + puts "\nHTML documentation is generated in \n$DOCDIR" + } + if { $generatorMode == "CHM_ONLY" } { + puts "\nGenerated CHM documentation is in \n$OUTDIR/overview.chm" + } + + puts "" + } + + # Remove temporary Doxygen files + set deleteList [glob -nocomplain -type f "*.tmp"] + foreach file $deleteList { + file delete $file + } + return 0 +} + +# Generates Doxygen configuration file for Overview documentation +proc OCCDoc_MakeDoxyfile {docType outDir tagFileDir {doxyFileName} {generatorMode ""} {DocFilesList {}} {ModulesList {}} verboseMode searchMode hhcPath mathjaxLocation graphvizPath productsPath} { + + set inputDir [OCCDoc_GetDoxDir] + set TEMPLATES_DIR $inputDir/resources + set occt_version [OCCDoc_DetectCasVersion] + + # Delete existent doxyfile + file delete $doxyFileName + + # Copy specific template to the target folder + if { $docType == "REFMAN" } { + file copy "$TEMPLATES_DIR/occt_rm.doxyfile" $doxyFileName + } elseif { $docType == "OVERVIEW" } { + if { $generatorMode == "HTML_ONLY" || $generatorMode == "CHM_ONLY" } { + file copy "$TEMPLATES_DIR/occt_ug_html.doxyfile" $doxyFileName + } elseif { $generatorMode == "PDF_ONLY"} { + file copy "$TEMPLATES_DIR/occt_ug_pdf.doxyfile" $doxyFileName + } else { + puts "Error: Unknown generation mode" + return -1 + } + } else { + puts "Error: Cannot generate unknown document type" + return -1 + } + + set doxyFile [open $doxyFileName "a"] + # Write specific options + if { $docType == "REFMAN" } { + + # Load lists of modules scripts + if { $productsPath == "" } { + set modules_scripts [glob -nocomplain -type f -directory "[OCCDoc_GetSourceDir $productsPath]/OS/" *.tcl] + } else { + set modules_scripts [glob -nocomplain -type f -directory "[OCCDoc_GetSourceDir $productsPath]/VAS/" *.tcl] + } + if { [llength $modules_scripts] != 0} { + foreach module_file $modules_scripts { + source $module_file + } + } + + set ALL_MODULES [OCCDoc_GetModulesList $productsPath] + if { [llength $ModulesList] == 0 } { + # by default take all modules + set modules $ALL_MODULES + } else { + set modules $ModulesList + } + + # Detect invalid names of modules + foreach module $modules { + if { $module == "" } { + continue + } + if {[lsearch $ALL_MODULES $module] == -1 } { + puts "Error: No module $module is known. Aborting..." + return -1 + } + } + + # Set context + set one_module [expr [llength $modules] == 1] + if { $one_module } { + set title "OCCT [$modules:name]" + set name $modules + } else { + set title "Open CASCADE Technology" + set name OCCT + } + + # Get list of header files in the specified modules + set filelist {} + foreach module $modules { + if { $module == "" } { + continue + } + foreach tk [$module:toolkits] { + foreach pk [split [OCCDoc_GetPackagesList [OCCDoc_Locate $tk $productsPath]]] { + if { [llength $pk] != "{}" } { + lappend filelist [OCCDoc_GetHeadersList "p" "pubinclude" "$pk" "$productsPath"] + } + } + } + } + + # Filter out files Handle_*.hxx and *.lxx + set hdrlist {} + foreach fileset $filelist { + set hdrset {} + foreach hdr $fileset { + if { ! [regexp {Handle_.*[.]hxx} $hdr] && ! [regexp {.*[.]lxx} $hdr] } { + lappend hdrset $hdr + } + } + lappend hdrlist $hdrset + } + set filelist $hdrlist + + set doxyFile [open $doxyFileName "a"] + + puts $doxyFile "PROJECT_NAME = \"$title\"" + puts $doxyFile "PROJECT_NUMBER = $occt_version" + puts $doxyFile "OUTPUT_DIRECTORY = $outDir/." + puts $doxyFile "GENERATE_TAGFILE = $outDir/${name}.tag" + + if { [string tolower $searchMode] == "none" } { + puts $doxyFile "SEARCHENGINE = NO" + puts $doxyFile "SERVER_BASED_SEARCH = NO" + puts $doxyFile "EXTERNAL_SEARCH = NO" + } else { + puts $doxyFile "SEARCHENGINE = YES" + if { [string tolower $searchMode] == "local" } { + puts $doxyFile "SERVER_BASED_SEARCH = NO" + puts $doxyFile "EXTERNAL_SEARCH = NO" + } elseif { [string tolower $searchMode] == "server" } { + puts $doxyFile "SERVER_BASED_SEARCH = YES" + puts $doxyFile "EXTERNAL_SEARCH = NO" + } elseif { [string tolower $searchMode] == "external" } { + puts $doxyFile "SERVER_BASED_SEARCH = YES" + puts $doxyFile "EXTERNAL_SEARCH = YES" + } else { + puts "Error: Wrong search engine type: $searchMode." + close $doxyFile + return -1 + } + } + + puts $doxyFile "DOTFILE_DIRS = $outDir/html" + puts $doxyFile "DOT_PATH = $graphvizPath" + puts $doxyFile "INCLUDE_PATH = [OCCDoc_GetIncDir $productsPath]" + + # list of files to generate + set mainpage [OCCDoc_MakeMainPage $outDir $outDir/$name.dox $modules $productsPath] + puts $doxyFile "" + puts $doxyFile "INPUT = $mainpage \\" + foreach header $filelist { + puts $doxyFile " $header \\" + } + + puts $doxyFile "MATHJAX_FORMAT = HTML-CSS" + puts $doxyFile "MATHJAX_RELPATH = ${mathjaxLocation}" + + puts $doxyFile "" + + } elseif { $docType == "OVERVIEW" } { + + # Add common options for generation of Overview and User Guides + puts $doxyFile "PROJECT_NUMBER = $occt_version" + puts $doxyFile "OUTPUT_DIRECTORY = $outDir/." + puts $doxyFile "PROJECT_LOGO = $inputDir/resources/occ_logo.png" + + set PARAM_INPUT "INPUT =" + set PARAM_IMAGEPATH "IMAGE_PATH = $inputDir/resources/ " + foreach docFile $DocFilesList { + set NEW_IMG_PATH "$inputDir/$docFile" + if { [string compare $NEW_IMG_PATH [OCCDoc_GetRootDir $productsPath]] != 0 } { + set img_string [file dirname $NEW_IMG_PATH]/images + if { [file exists $img_string] } { + append PARAM_IMAGEPATH " $img_string" + } + } + append PARAM_INPUT " " $inputDir/$docFile + } + puts $doxyFile $PARAM_INPUT + puts $doxyFile $PARAM_IMAGEPATH + + # Add document type-specific options + if { $generatorMode == "HTML_ONLY"} { + # generate tree view + puts $doxyFile "GENERATE_TREEVIEW = YES" + + # Set a reference to a TAGFILE + if { $tagFileDir != "" } { + if {[file exists $tagFileDir/OCCT.tag] == 1} { + #set tagPath [OCCDoc_GetRelPath $tagFileDir $outDir/html] + set tagPath $tagFileDir + puts $doxyFile "TAGFILES = $tagFileDir/OCCT.tag=../../refman/html" + } + } + # HTML Search engine options + if { [string tolower $searchMode] == "none" } { + puts $doxyFile "SEARCHENGINE = NO" + puts $doxyFile "SERVER_BASED_SEARCH = NO" + puts $doxyFile "EXTERNAL_SEARCH = NO" + } else { + puts $doxyFile "SEARCHENGINE = YES" + if { [string tolower $searchMode] == "local" } { + puts $doxyFile "SERVER_BASED_SEARCH = NO" + puts $doxyFile "EXTERNAL_SEARCH = NO" + } elseif { [string tolower $searchMode] == "server" } { + puts $doxyFile "SERVER_BASED_SEARCH = YES" + puts $doxyFile "EXTERNAL_SEARCH = NO" + } elseif { [string tolower $searchMode] == "external" } { + puts $doxyFile "SERVER_BASED_SEARCH = YES" + puts $doxyFile "EXTERNAL_SEARCH = YES" + } else { + puts "Error: Wrong search engine type: $searchMode." + close $doxyFile + return -1 + } + } + } elseif { $generatorMode == "CHM_ONLY"} { + # specific options for CHM file generation + puts $doxyFile "GENERATE_TREEVIEW = NO" + puts $doxyFile "SEARCHENGINE = NO" + puts $doxyFile "GENERATE_HTMLHELP = YES" + puts $doxyFile "CHM_FILE = ../../overview.chm" + puts $doxyFile "HHC_LOCATION = \"$hhcPath\"" + puts $doxyFile "DISABLE_INDEX = YES" + } + + # Formula options + puts $doxyFile "MATHJAX_RELPATH = ${mathjaxLocation}" + } + + close $doxyFile + return 0 +} diff --git a/adm/occaux.tcl b/adm/occaux.tcl new file mode 100644 index 0000000000..161fd74ab4 --- /dev/null +++ b/adm/occaux.tcl @@ -0,0 +1,897 @@ +# ======================================================================= +# Created on: 2014-03-21 +# Created by: OMY +# Copyright (c) 1996-1999 Matra Datavision +# Copyright (c) 1999-2014 OPEN CASCADE SAS +# +# This file is part of Open CASCADE Technology software library. +# +# This library is free software; you can redistribute it and/or modify it under +# the terms of the GNU Lesser General Public License version 2.1 as published +# by the Free Software Foundation, with special exception defined in the file +# OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT +# distribution for complete text of the license and disclaimer of any warranty. +# +# Alternatively, this file may be used under the terms of Open CASCADE +# commercial license or contractual agreement. +# +# Brief: This script contains auxilary functions which can be used +# in documentation generation process +# ======================================================================= + +# ============================================== +# Commonly used functions +# ============================================== + +# Parses arguments line like "-arg1=val1 -arg2=val2 ..." to array args_names and map args_values +proc OCCDoc_ParseArguments {arguments} { + global args_names + global args_values + set args_names {} + array set args_values {} + + foreach arg $arguments { + if {[regexp {^(-)[a-z]+$} $arg] == 1} { + set name [string range $arg 1 [string length $arg]-1] + lappend args_names $name + set args_values($name) "NULL" + continue + } elseif {[regexp {^(-)[a-z]+=.+$} $arg] == 1} { + set equal_symbol_position [string first "=" $arg] + set name [string range $arg 1 $equal_symbol_position-1] + lappend args_names $name + set value [string range $arg $equal_symbol_position+1 [string length $arguments]-1] + + # To parse a list of values for -m parameter + if { [string first "," $value] != -1 } { + set value [split $value ","]; + } + + set args_values($name) $value + + } else { + puts "Error in argument $arg." + return 1 + } + } + return 0 +} + +# Returns script parent folder +proc OCCDoc_GetDoxDir {} { + return [file normalize [file dirname [info script]]/../dox] +} + +# Returns OCCT root dir +proc OCCDoc_GetOCCTRootDir {} { + set path [OCCDoc_GetDoxDir] + return [file normalize $path/..] +} + +# Returns root dir +proc OCCDoc_GetRootDir { {theProductsPath ""} } { + + if { $theProductsPath == "" } { + return [OCCDoc_GetOCCTRootDir] + } else { + return [file normalize $theProductsPath] + } +} + +# Returns OCCT include dir +proc OCCDoc_GetIncDir { {theProductsPath ""} } { + set path [OCCDoc_GetRootDir $theProductsPath] + return "$path/inc" +} + +# Returns OCCT source dir +proc OCCDoc_GetSourceDir { {theProductsPath ""} } { + set path [OCCDoc_GetRootDir $theProductsPath] + return "$path/src" +} + +# Returns name of the package from the current toolkit +proc OCCDoc_GetNameFromPath { thePath } { + + set splitted_path [split $thePath "/" ] + set package_name [lindex $splitted_path end] + + return $package_name +} + +# Returns the relative path between two folders +proc OCCDoc_GetRelPath {thePathFrom thePathTo} { + if { [file isdirectory "$thePathFrom"] == 0 } { + return "" + } + + set aPathFrom [file normalize "$thePathFrom"] + set aPathTo [file normalize "$thePathTo"] + + set aCutedPathFrom "${aPathFrom}/dummy" + set aRelatedDeepPath "" + + while { "$aCutedPathFrom" != [file normalize "$aCutedPathFrom/.."] } { + set aCutedPathFrom [file normalize "$aCutedPathFrom/.."] + # does aPathTo contain aCutedPathFrom? + regsub -all $aCutedPathFrom $aPathTo "" aPathFromAfterCut + if { "$aPathFromAfterCut" != "$aPathTo" } { # if so + if { "$aCutedPathFrom" == "$aPathFrom" } { # just go higher, for example, ./somefolder/someotherfolder + set aPathTo ".${aPathTo}" + } elseif { "$aCutedPathFrom" == "$aPathTo" } { # remove the last "/" + set aRelatedDeepPath [string replace $aRelatedDeepPath end end ""] + } + regsub -all $aCutedPathFrom $aPathTo $aRelatedDeepPath aPathToAfterCut + regsub -all "//" $aPathToAfterCut "/" aPathToAfterCut + return $aPathToAfterCut + } + set aRelatedDeepPath "$aRelatedDeepPath../" + } + + return $thePathTo +} + +# Returns OCCT version string from file Standard_Version.hxx (if available) +proc OCCDoc_DetectCasVersion {} { + set occt_ver 6.7.0 + set occt_ver_add "" + set filename "[OCCDoc_GetSourceDir]/Standard/Standard_Version.hxx" + if { [file exists $filename] } { + set fh [open $filename "r"] + set fh_loaded [read $fh] + close $fh + regexp {[^/]\s*#\s*define\s+OCC_VERSION_COMPLETE\s+\"([^\s]*)\"} $fh_loaded dummy occt_ver + regexp {[^/]\s*#\s*define\s+OCC_VERSION_DEVELOPMENT\s+\"([^\s]*)\"} $fh_loaded dummy occt_ver_add + if { "$occt_ver_add" != "" } { set occt_ver ${occt_ver}.$occt_ver_add } + } + return $occt_ver +} + +# Checks if the necessary tools exist +proc OCCDoc_DetectNecessarySoftware { DOXYGEN_PATH GRAPHVIZ_PATH INKSCAPE_PATH HHC_PATH PDFLATEX_PATH } { + + upvar 1 DOXYGEN_PATH doxy_path + upvar 1 GRAPHVIZ_PATH graph_path + upvar 1 INKSCAPE_PATH inkscape_path + upvar 1 HHC_PATH hhc_path + upvar 1 PDFLATEX_PATH latex_path + + set doxy_path "" + set graph_path "" + set inkscape_path "" + set latex_path "" + set hhc_path "" + + set is_win "no" + if { "$::tcl_platform(platform)" == "windows" } { + set is_win "yes" + } + if {"$is_win" == "yes"} { + set exe ".exe" + } else { + set exe "" + } + + set g_flag "no" + set d_flag "no" + set i_flag "no" + set h_flag "no" + set l_flag "no" + + puts "" + set envPath $::env(PATH) + if { $is_win == "yes" } { + set searchPathsList [split $envPath ";"] + } else { + set searchPathsList [split $envPath ":"] + } + + foreach path $searchPathsList { + if { ($is_win == "no") && + (($path == "/usr/bin") || ($path == "/usr/local/bin")) } { + # Avoid searching in default bin location + continue + } + if {$d_flag == "no"} { + if { [file exists $path/doxygen$exe] } { + catch { exec $path/doxygen -V } version_string + set version [lindex [split $version_string "\n"] 0] + puts "Info: $version " + puts " found in $path." + set doxy_path "$path/doxygen$exe" + set d_flag "yes" + } + } + if {$g_flag == "no"} { + if { [file exists $path/dot$exe] } { + catch { exec $path/dot -V } version + + puts "Info: $version " + puts " found in $path." + set graph_path "$path/dot$exe" + set g_flag "yes" + } + } + if {$i_flag == "no"} { + if { [file exists $path/inkscape$exe] } { + catch { exec $path/inkscape -V } version + puts "Info: $version " + puts " found in $path." + set inkscape_path "$path/inkscape$exe" + set i_flag "yes" + } + } + if {$l_flag == "no"} { + if { [file exists $path/pdflatex$exe] } { + catch { exec $path/pdflatex -version } version + set version [lindex [split $version "\n"] 0] + puts "Info: $version " + puts " found in $path." + set latex_path "$path/pdflatex$exe" + set l_flag "yes" + } + } + if { ("$is_win" == "yes") && ($h_flag == "no") } { + if { [file exists $path/hhc.exe] } { + puts "Info: hhc " + puts " found in $path." + set hhc_path "hhc$exe" + set h_flag "yes" + } + } + if { ($d_flag == "yes") && + ($i_flag == "yes") && + ($g_flag == "yes") && + ($l_flag == "yes") && + (($is_win == "yes") && + ($h_flag == "yes")) } { + break + } + } + + # On Windows search for hhc.exe in the default location + # if it has not been found yet + if { ("$is_win" == "yes") && ($h_flag == "no") } { + if { [info exists ::env(ProgramFiles\(x86\))] } { + set h_flag "yes" + set path "$::env(ProgramFiles\(x86\))\\HTML Help Workshop" + set hhc_path "$path\\hhc.exe" + puts "Info: hhc " + puts " found in $path." + } else { + if { [info exists ::env(ProgramFiles)] } { + set h_flag "yes" + set path "$::env(ProgramFiles)\\HTML Help Workshop" + set hhc_path "$path\\hhc.exe" + puts "Info: hhc" + puts " found in $path." + } + } + } + + # On *nix-like platforms, + # check the default binary locations if the tools had not been found yet + if { $is_win == "no" && + (($d_flag == "no") || + ($i_flag == "no") || + ($g_flag == "no") || + ($l_flag == "no")) } { + + set default_path { "/usr/bin" "/usr/local/bin" } + foreach path $default_path { + if {$d_flag == "no"} { + if { [file exists $path/doxygen$exe] } { + catch { exec $path/doxygen -V } version_string + set version [lindex [split $version_string "\n"] 0] + puts "Info: $version " + puts " found in $path." + set doxy_path "$path/doxygen$exe" + set d_flag "yes" + } + } + if {$g_flag == "no"} { + if { [file exists $path/dot$exe] } { + catch { exec $path/dot -V } version + + puts "Info: $version " + puts " found in $path." + set graph_path "$path/dot$exe" + set g_flag "yes" + } + } + if {$i_flag == "no"} { + if { [file exists $path/inkscape$exe] } { + catch { exec $path/inkscape -V } version + puts "Info: $version " + puts " found in $path." + set inkscape_path "$path/inkscape$exe" + set i_flag "yes" + } + } + if {$l_flag == "no"} { + if { [file exists $path/pdflatex$exe] } { + catch { exec $path/pdflatex -version } version + set version [lindex [split $version "\n"] 0] + puts "Info: $version " + puts " found in $path." + set latex_path "$path/pdflatex$exe" + set l_flag "yes" + } + } + } + } + + # Check if tools have been found + if { $d_flag == "no" } { + puts "Warning: Could not find doxygen installed." + return -1 + } + if { $g_flag == "no" } { + puts "Warning: Could not find graphviz installed." + } + if { $i_flag == "no" } { + puts "Warning: Could not find inkscape installed." + } + if { $l_flag == "no" } { + puts "Warning: Could not find pdflatex installed." + } + if { ("$::tcl_platform(platform)" == "windows") && ($h_flag == "no") } { + puts "Warning: Could not find hhc installed." + } + + puts "" +} + +# Convert SVG files to PDF format to allow including them to PDF +# (requires InkScape to be in PATH) +proc OCCDoc_ProcessSvg {latexDir verboseMode} { + + foreach file [glob -nocomplain $latexDir/*.svg] { + if {$verboseMode == "YES"} { + puts "Info: Converting file $file..." + } + set pdffile "[file rootname $file].pdf" + if { [catch {exec inkscape -z -D --file=$file --export-pdf=$pdffile} res] } { + #puts "Error: $res." + return + } + } +} + +# ============================================== +# Reference Manual-specific functions +# ============================================== + +# Finds dependencies between all modules +proc OCCDoc_CreateModulesDependencyGraph {dir filename modules mpageprefix} { + global module_dependency + + if {![catch {open $dir/$filename.dot "w"} file]} { + puts $file "digraph $filename" + puts $file "\{" + + foreach mod $modules { + if { $mod == "" } { + continue + } + puts $file "\t$mod \[ URL = \"[string tolower $mpageprefix$mod.html]\" \]" + foreach mod_depend $module_dependency($mod) { + puts $file "\t$mod_depend -> $mod \[ dir = \"back\", color = \"midnightblue\", style = \"solid\" \]" + } + } + + puts $file "\}" + close $file + + return $filename + } +} + +# Finds dependencies between all toolkits in module +proc OCCDoc_CreateModuleToolkitsDependencyGraph {dir filename modulename tpageprefix} { + global toolkits_in_module + global toolkit_dependency + global toolkit_parent_module + + if {![catch {open $dir/$filename.dot "w"} file]} { + puts $file "digraph $filename" + puts $file "\{" + + foreach tk $toolkits_in_module($modulename) { + puts $file "\t$tk \[ URL = \"[string tolower $tpageprefix$tk.html]\"\ ]" + foreach tkd $toolkit_dependency($tk) { + if { [info exists toolkit_parent_module($tkd)] } { + if {$toolkit_parent_module($tkd) == $modulename} { + puts $file "\t$tkd -> $tk \[ dir = \"back\", color = \"midnightblue\", style = \"solid\" \]" + } + } + } + } + + puts $file "\}" + close $file + + return $filename + } +} + +# Finds dependencies between the current toolkit and other toolkits +proc OCCDoc_CreateToolkitDependencyGraph {dir filename toolkitname tpageprefix} { + global toolkit_dependency + + if {![catch {open $dir/$filename.dot "w"} file]} { + puts $file "digraph $filename" + puts $file "\{" + + puts $file "\t$toolkitname \[ URL = \"[string tolower $tpageprefix$toolkitname.html]\"\, shape = box ]" + foreach tkd $toolkit_dependency($toolkitname) { + puts $file "\t$tkd \[ URL = \"[string tolower $tpageprefix$tkd.html]\"\ , shape = box ]" + puts $file "\t$toolkitname -> $tkd \[ color = \"midnightblue\", style = \"solid\" \]" + } + + if {[llength $toolkit_dependency($toolkitname)] > 1} { + puts $file "\taspect = 1" + } + + puts $file "\}" + close $file + + return $filename + } +} + +# Fills arrays of modules, toolkits, dependency of modules/toolkits etc +proc OCCDoc_LoadData { {theProductsDir ""} } { + global toolkits_in_module + global toolkit_dependency + global toolkit_parent_module + global module_dependency + + if { $theProductsDir == ""} { + set modules_files [glob -nocomplain -type f -directory "[OCCDoc_GetSourceDir $theProductsDir]/OS/" *.tcl] + } else { + set modules_files [glob -nocomplain -type f -directory "[OCCDoc_GetSourceDir $theProductsDir]/VAS/" *.tcl] + } + + foreach module_file $modules_files { + source $module_file + } + + set modules [OCCDoc_GetModulesList $theProductsDir] + foreach mod $modules { + + if { $mod == "" } { + continue + } + # Get toolkits of current module + set toolkits_in_module($mod) [$mod:toolkits] + # Get all dependence of current toolkit + foreach tk $toolkits_in_module($mod) { + # set parent module of current toolkit + set toolkit_parent_module($tk) $mod + set exlibfile [open "[OCCDoc_GetSourceDir $theProductsDir]/$tk/EXTERNLIB" r] + set exlibfile_data [read $exlibfile] + set exlibfile_data [split $exlibfile_data "\n"] + + set toolkit_dependency($tk) {} + foreach dtk $exlibfile_data { + if { ([string first "TK" $dtk 0] == 0) || + ([string first "P" $dtk 0] == 0) } { + lappend toolkit_dependency($tk) $dtk + } + } + close $exlibfile + } + } + + # Get modules dependency + foreach mod $modules { + set module_dependency($mod) {} + foreach tk $toolkits_in_module($mod) { + foreach tkd $toolkit_dependency($tk) { + if { [info exists toolkit_parent_module($tkd)] } { + if { $toolkit_parent_module($tkd) != $mod && + [lsearch $module_dependency($mod) $toolkit_parent_module($tkd)] == -1} { + lappend module_dependency($mod) $toolkit_parent_module($tkd) + } + } + } + } + } +} + +# Returns list of packages of the given toolkit +proc OCCDoc_GetPackagesList { theToolKitPath } { + + set packages_list {} + + # Open file with list of packages of the given toolkit + set fileid [open "$theToolKitPath/PACKAGES" "r"] + + while { [eof $fileid] == 0 } { + set str [gets $fileid] + if { $str != "" } { + lappend packages_list $str + } + } + + close $fileid + + return $packages_list +} + +# Returns list of modules from UDLIST +proc OCCDoc_GetModulesList { {theProductsDir ""} } { + + if { $theProductsDir == "" } { + source "[OCCDoc_GetSourceDir $theProductsDir]/OS/Modules.tcl" + # load a command from this file + set modules [OS:Modules] + } else { + source "[OCCDoc_GetSourceDir $theProductsDir]/VAS/Products.tcl" + # load a command from this file + set modules [VAS:Products] + } + + return $modules +} + +# Returns list of desired files in the specified location +proc OCCDoc_GetHeadersList { theDesiredContent theFileType thePackageName {theProductsDir ""} } { + + # Get file type + set file_type_pattern "*.*" + if { $theFileType == "pubinclude" } { + set file_type_pattern "*.*" + } elseif { $theFileType == "privinclude" } { + set file_type_pattern "*.ixx" + } + + # Get content according to desired type ('p' for path and 'f' for filenames only) + if { $theDesiredContent == "p" } { + + # Get list of files with path + set files_list [split [glob -nocomplain -type f -directory "[OCCDoc_GetIncDir $theProductsDir]" "$thePackageName$file_type_pattern"]] + + return $files_list + } elseif { $theDesiredContent == "f" } { + # Get list of files without path + set files_list [split [glob -nocomplain -type f -directory "[OCCDoc_GetIncDir $theProductsDir]" "$thePackageName$file_type_pattern"]] + + # Cut paths from filenames + foreach file $files_list { + set elem_index [lsearch $files_list $file] + lset files_list $elem_index [OCCDoc_GetNameFromPath [lindex $files_list $elem_index]] + } + return $files_list + } +} + +# Returns location of the toolkit +proc OCCDoc_Locate { theToolKitName {theProductsDir ""} } { + set tk_dir "[OCCDoc_GetSourceDir $theProductsDir]/[OCCDoc_GetNameFromPath $theToolKitName]" + return $tk_dir +} + +# Gets contents of the given html node (for Post-processing) +proc OCCDoc_GetNodeContents {node props html} { + set openTag "<$node$props>" + set closingTag "" + set start [string first $openTag $html] + if {$start == -1} { + return "" + } + set start [expr $start + [string length $openTag]] + set end [string length $html] + set html [string range $html $start $end] + set start [string first $closingTag $html] + set end [string length $html] + if {$start == -1} { + return "" + } + set start [expr $start - 1] + return [string range $html 0 $start] +} + +# Generates main page file describing module structure +proc OCCDoc_MakeMainPage {outDir outFile modules {theProductsDir ""} } { + global env + + set one_module [expr [llength $modules] == 1] + set fd [open $outFile "w"] + + set module_prefix "module_" + set toolkit_prefix "toolkit_" + set package_prefix "package_" + + if { ! [file exists "$outDir/html"] } { + file mkdir "$outDir/html" + } + + OCCDoc_LoadData $theProductsDir + + # Main page: list of modules + if { ! $one_module } { + puts $fd "/**" + puts $fd "\\mainpage Open CASCADE Technology" + + foreach mod $modules { + puts $fd "\\li \\subpage [string tolower $module_prefix$mod]" + } + # insert modules relationship diagramm + puts $fd "\\dotfile [OCCDoc_CreateModulesDependencyGraph $outDir/html schema_all_modules $modules $module_prefix]" + puts $fd "**/\n" + } + + # One page per module: list of toolkits + set toolkits {} + foreach mod $modules { + if { $mod == "" } { + continue + } + puts $fd "/**" + if { $one_module } { + puts $fd "\\mainpage OCCT Module [$mod:name]" + } else { + puts $fd "\\page [string tolower module_$mod] Module [$mod:name]" + } + foreach tk [lsort [$mod:toolkits]] { + lappend toolkits $tk + puts $fd "\\li \\subpage [string tolower $toolkit_prefix$tk]" + } + puts $fd "\\dotfile [OCCDoc_CreateModuleToolkitsDependencyGraph $outDir/html schema_$mod $mod $toolkit_prefix]" + puts $fd "**/\n" + } + + # One page per toolkit: list of packages + set packages {} + foreach tk $toolkits { + puts $fd "/**" + puts $fd "\\page [string tolower toolkit_$tk] Toolkit $tk" + foreach pk [lsort [OCCDoc_GetPackagesList [OCCDoc_Locate $tk $theProductsDir]]] { + lappend packages $pk + set u [OCCDoc_GetNameFromPath $pk] + puts $fd "\\li \\subpage [string tolower $package_prefix$u]" + } + puts $fd "\\dotfile [OCCDoc_CreateToolkitDependencyGraph $outDir/html schema_$tk $tk $toolkit_prefix]" + puts $fd "**/\n" + } + + # One page per package: list of classes + foreach pk $packages { + set u [OCCDoc_GetNameFromPath $pk] + puts $fd "/**" + puts $fd "\\page [string tolower $package_prefix$u] Package $u" + foreach hdr [lsort [OCCDoc_GetHeadersList "f" "pubinclude" "$pk" "$theProductsDir"]] { + if { ! [regexp {^Handle_} $hdr] && [regexp {(.*)[.]hxx} $hdr str obj] } { + puts $fd "\\li \\subpage $obj" + } + } + puts $fd "**/\n" + } + + close $fd + + return $outFile +} + +# Parses generated files to add a navigation path +proc OCCDoc_PostProcessor {outDir} { + puts "[clock format [clock seconds] -format {%Y.%m.%d %H:%M}] Post-process is started ..." + append outDir "/html" + set files [glob -nocomplain -type f $outDir/package_*] + if { $files != {} } { + foreach f [lsort $files] { + set packageFilePnt [open $f r] + set packageFile [read $packageFilePnt] + set navPath [OCCDoc_GetNodeContents "div" " id=\"nav-path\" class=\"navpath\"" $packageFile] + set packageName [OCCDoc_GetNodeContents "div" " class=\"title\"" $packageFile] + regsub -all {<[^<>]*>} $packageName "" packageName + + # add package link to nav path + set first [expr 1 + [string last "/" $f]] + set last [expr [string length $f] - 1] + set packageFileName [string range $f $first $last] + set end [string first "" $navPath] + set end [expr $end - 1] + set navPath [string range $navPath 0 $end] + append navPath "
  • $packageName
  • \n " + + # get list of files to update + set listContents [OCCDoc_GetNodeContents "div" " class=\"textblock\"" $packageFile] + set listContents [OCCDoc_GetNodeContents "ul" "" $listContents] + set lines [split $listContents "\n"] + foreach line $lines { + if {[regexp {href=\"([^\"]*)\"} $line tmpLine classFileName]} { + # check if anchor is there + set anchorPos [string first "#" $classFileName] + if {$anchorPos != -1} { + set classFileName [string range $classFileName 0 [expr $anchorPos - 1]] + } + + # read class file + set classFilePnt [open $outDir/$classFileName r+] + set classFile [read $classFilePnt] + + # find position of content block + set contentPos [string first "
    " $classFile] + set navPart [string range $classFile 0 [expr $contentPos - 1]] + + # position where to insert nav path + set posToInsert [string last "
    " $navPart] + set prePart [string range $classFile 0 [expr $posToInsert - 1]] + set postPart [string range $classFile $posToInsert [string length $classFile]] + set newClassFile "" + append newClassFile $prePart "
    " $navPath \n "
    " \n $postPart + + # write updated content + seek $classFilePnt 0 + puts $classFilePnt $newClassFile + close $classFilePnt + } + } + close $packageFilePnt + } + return 0 + } else { + puts "no files found" + return 1 + } +} + +# ====================================== +# User Guides-specific functions +# ====================================== + +# Loads a list of docfiles from file FILES.txt +proc OCCDoc_LoadFilesList {} { + + set INPUTDIR [OCCDoc_GetDoxDir] + + global available_docfiles + set available_docfiles {} + + # Read data from file + if { [file exists "$INPUTDIR/FILES_HTML.txt"] == 1 } { + set FILE [open "$INPUTDIR/FILES_HTML.txt" r] + while {1} { + set line [string trim [gets $FILE]] + + # trim possible comments starting with '#' + set line [regsub {\#.*} $line {}] + if {$line != ""} { + lappend available_docfiles $line + } + if {[eof $FILE]} { + close $FILE + break + } + } + } else { + return -1 + } + + global available_pdf + set available_pdf {} + + # Read data from file + if { [file exists "$INPUTDIR/FILES_PDF.txt"] } { + set FILE [open "$INPUTDIR/FILES_PDF.txt" r] + while {1} { + set line [string trim [gets $FILE]] + + # Trim possible comments starting with '#' + set line [regsub {\#.*} $line {}] + if {$line != ""} { + lappend available_pdf $line + } + if {[eof $FILE]} { + close $FILE + break + } + } + } else { + return -1 + } + return 0 +} + +# Writes new TeX file for conversion from tex to pdf for a specific doc +proc OCCDoc_MakeRefmanTex {fileName latexDir verboseMode latexFilesList} { + + if { $verboseMode == "YES" } { + puts "Info: Making refman.tex file for $fileName..." + } + set DOCNAME "$latexDir/refman.tex" + if {[file exists $DOCNAME] == 1} { + file delete -force $DOCNAME + } + + # Copy template file to latex folder + file copy "[OCCDoc_GetDoxDir]/resources/occt_pdf_template.tex" $DOCNAME + + # Get templatized data + set texfile [open $DOCNAME "r"] + set texfile_loaded [read $texfile] + close $texfile + + # Replace dummy values + set year [clock format [clock seconds] -format {%Y}] + set texfile [open $DOCNAME "w"] + set casVersion [OCCDoc_DetectCasVersion] + + # Get name of the document + set docLabel "" + foreach aFileName $latexFilesList { + # Find the file in FILES_PDF.txt + set parsedFileName [split $aFileName "/" ] + set newfileName [string range $fileName [expr [string first "__" $fileName] + 2] end] + + if { [lsearch -nocase $parsedFileName "$newfileName.md" ] != -1 } { + set filepath "[OCCDoc_GetDoxDir]/$aFileName" + if { [file exists $filepath] } { + set MDFile [open $filepath "r"] + set label [split [gets $MDFile] "\{"] + set docLabel [lindex $label 0] + close $MDFile + + break + } + } + } + + set texfile_loaded [string map [list DEFDOCLABEL "$docLabel" DEFCASVERSION "$casVersion" DEFFILENAME "$fileName" DEFYEAR "$year"] $texfile_loaded] + + # Get data + puts $texfile $texfile_loaded + + close $texfile +} + +# Postprocesses generated TeX files +proc OCCDoc_ProcessTex {{texFiles {}} {latexDir} verboseMode} { + + foreach TEX $texFiles { + if {$verboseMode == "YES"} { + puts "Info: Preprocessing file $TEX..." + } + + if {![file exists $TEX]} { + puts "Error: file $TEX does not exist." + return -1 + } + + set IN_F [open "$TEX" "r"] + set TMPFILENAME "$latexDir/temp.tex" + set OUT_F [open $TMPFILENAME w] + + while {1} { + set line [gets $IN_F] + if { [string first "\\includegraphics" $line] != -1 } { + # replace svg extension by pdf + set line [regsub {[.]svg} $line ".pdf"] + # Center images in TeX files + set line "\\begin{center}\n $line\n\\end{center}" + } elseif { [string first "\\subsection" $line] != -1 } { + # Replace \subsection with \section tag + regsub -all "\\\\subsection" $line "\\\\section" line + } elseif { [string first "\\subsubsection" $line] != -1 } { + # Replace \subsubsection with \subsection tag + regsub -all "\\\\subsubsection" $line "\\\\subsection" line + } elseif { [string first "\\paragraph" $line] != -1 } { + # Replace \paragraph with \subsubsection tag + regsub -all "\\\\paragraph" $line "\\\\subsubsection" line + } + puts $OUT_F $line + + if {[eof $IN_F]} { + close $IN_F + close $OUT_F + break + } + } + + file delete -force $TEX + file rename $TMPFILENAME $TEX + } +} diff --git a/adm/start.tcl b/adm/start.tcl new file mode 100644 index 0000000000..b9d4c70f1c --- /dev/null +++ b/adm/start.tcl @@ -0,0 +1,8 @@ +#!/usr/bin/tclsh + +# Command-line starter for occdoc command, use it as follows: +# tclsh> source dox/start.tcl [arguments] + +source [file join [file dirname [info script]] occaux.tcl] +source [file join [file dirname [info script]] gendoc.tcl] +gendoc {*}$::argv diff --git a/dox/FILES.txt b/dox/FILES_HTML.txt similarity index 100% rename from dox/FILES.txt rename to dox/FILES_HTML.txt diff --git a/dox/FILES_PDF.txt b/dox/FILES_PDF.txt new file mode 100644 index 0000000000..69ac568aca --- /dev/null +++ b/dox/FILES_PDF.txt @@ -0,0 +1,32 @@ +# This file contains list of documentation files of OCCT which are processed +# by Doxygen to generate PDF documentation. +# Files are listed one file per line, with paths relative to dox folder. +# Empty spaces are allowed. +# Strings starting with '#' are treated as comments and ignored. + +user_guides/brep_wp/brep_wp.md +user_guides/foundation_classes/foundation_classes.md +user_guides/iges/iges.md +user_guides/modeling_data/modeling_data.md +user_guides/modeling_algos/modeling_algos.md +user_guides/ocaf/ocaf.md +user_guides/ocaf_functionmechanism_wp/ocaf_functionmechanism_wp.md +user_guides/ocaf_tree_wp/ocaf_tree_wp.md +user_guides/ocaf_wp/ocaf_wp.md +user_guides/shape_healing/shape_healing.md +user_guides/step/step.md +user_guides/draw_test_harness.md +user_guides/tobj/tobj.md +user_guides/visualization/visualization.md +user_guides/voxels_wp/voxels_wp.md +user_guides/xde/xde.md + +dev_guides/contribution_workflow/contribution_workflow.md +dev_guides/documentation/documentation.md +dev_guides/contribution/coding_rules.md +dev_guides/git_guide/git_guide.md +dev_guides/tests/tests.md +dev_guides/wok/wok.md +dev_guides/cdl/cdl.md + +tutorial/tutorial.md diff --git a/dox/dev_guides/building/3rdparty/3rdparty_linux.md b/dox/dev_guides/building/3rdparty/3rdparty_linux.md index eef98ae833..4699a22ff9 100644 --- a/dox/dev_guides/building/3rdparty/3rdparty_linux.md +++ b/dox/dev_guides/building/3rdparty/3rdparty_linux.md @@ -1,4 +1,4 @@ - Building 3rd-party libraries on Linux {#dev_guides__building_3rdparty_linux} + Building 3rd-party libraries on Linux {#occt_dev_guides__building_3rdparty_linux} ========= @tableofcontents diff --git a/dox/dev_guides/building/3rdparty/3rdparty_osx.md b/dox/dev_guides/building/3rdparty/3rdparty_osx.md index 88bd211e9e..211696ef13 100644 --- a/dox/dev_guides/building/3rdparty/3rdparty_osx.md +++ b/dox/dev_guides/building/3rdparty/3rdparty_osx.md @@ -1,4 +1,4 @@ - Building 3rd-party libraries on MacOS X {#dev_guides__building_3rdparty_osx} + Building 3rd-party libraries on MacOS X {#occt_dev_guides__building_3rdparty_osx} ============================================== @tableofcontents diff --git a/dox/dev_guides/building/3rdparty/3rdparty_windows.md b/dox/dev_guides/building/3rdparty/3rdparty_windows.md index 6a68c2ac35..38cde800ee 100644 --- a/dox/dev_guides/building/3rdparty/3rdparty_windows.md +++ b/dox/dev_guides/building/3rdparty/3rdparty_windows.md @@ -1,4 +1,4 @@ - Building 3rd-party libraries on Windows {#dev_guides__building_3rdparty_windows} + Building 3rd-party libraries on Windows {#occt_dev_guides__building_3rdparty_windows} ============================================== @tableofcontents diff --git a/dox/dev_guides/building/automake.md b/dox/dev_guides/building/automake.md index ed53803708..d700b86bfe 100644 --- a/dox/dev_guides/building/automake.md +++ b/dox/dev_guides/building/automake.md @@ -1,4 +1,4 @@ -Building with Automake {#dev_guides__building__automake} +Building with Automake {#occt_dev_guides__building_automake} ====================== This file describes steps to build OCCT libraries from complete source @@ -6,10 +6,10 @@ archive on Linux with GNU build system (Autotools). If you are building OCCT from bare sources (as in Git repository), or do some changes affecting CDL files, you need to use WOK to re-generate header files -and build scripts / projects. See paragraph 1 \ref dev_guides__building__wok for instructions. +and build scripts / projects. See paragraph 1 \ref occt_dev_guides__building_wok for instructions. Before building OCCT, you need to install required third-party libraries; see paragraph 1 of -\ref dev_guides__building for instructions. +\ref occt_dev_guides__building for instructions. Note that during compilation by makefiles on some Linux OS on a station with NVIDIA video card you may experience problems because the installation diff --git a/dox/dev_guides/building/building.md b/dox/dev_guides/building/building.md index 9df63a7265..373d2787ff 100644 --- a/dox/dev_guides/building/building.md +++ b/dox/dev_guides/building/building.md @@ -1,4 +1,4 @@ -Building OCCT from sources {#dev_guides__building} +Building OCCT from sources {#occt_dev_guides__building} ========= In order to build OCCT libraries from these sources for use in your program, @@ -9,24 +9,23 @@ you need to: See the following documents for short guide to installation of third-party libraries on different platforms: - - \subpage dev_guides__building_3rdparty_windows - - \subpage dev_guides__building_3rdparty_linux - - \subpage dev_guides__building_3rdparty_osx - + - \subpage occt_dev_guides__building_3rdparty_windows + - \subpage occt_dev_guides__building_3rdparty_linux + - \subpage occt_dev_guides__building_3rdparty_osx 2. If you use bare OCCT sources from Git repository or made some changes affecting CDL files or dependencies of OCCT toolkits, you need to update header files generated - from \ref dev_guides__cdl "CDL", and regenerate build scripts for your environment using WOK. - See \subpage dev_guides__building__wok for details. + from \ref occt_dev_guides__cdl "CDL", and regenerate build scripts for your environment using WOK. + See \subpage occt_dev_guides__building_wok for details. Skip to step 3 if you use complete source package (e.g. official OCCT release) without changes in CDL. 3. Build using your preferred build tool. - - \subpage dev_guides__building__automake "Building on Linux with Autotools" - - \subpage dev_guides__building__cmake "Building with CMake (cross-platform)" - - \subpage dev_guides__building__code_blocks "Building on Mac OS X with Code::Blocks" - - \subpage dev_guides__building__msvc "Building on Windows with MS Visual Studio" - - \subpage dev_guides__building__xcode "Building on Mac OS X with Xcode" + - \subpage occt_dev_guides__building_automake "Building on Linux with Autotools" + - \subpage occt_dev_guides__building_cmake "Building with CMake (cross-platform)" + - \subpage occt_dev_guides__building_code_blocks "Building on Mac OS X with Code::Blocks" + - \subpage occt_dev_guides__building_msvc "Building on Windows with MS Visual Studio" + - \subpage occt_dev_guides__building_xcode "Building on Mac OS X with Xcode" The current version of OCCT can be consulted in the file src/Standard/Standard_Version.hxx \ No newline at end of file diff --git a/dox/dev_guides/building/cmake/cmake.md b/dox/dev_guides/building/cmake/cmake.md index 98fb625db5..9f6dd40747 100644 --- a/dox/dev_guides/building/cmake/cmake.md +++ b/dox/dev_guides/building/cmake/cmake.md @@ -1,4 +1,4 @@ -Building with CMake {#dev_guides__building__cmake} +Building with CMake {#occt_dev_guides__building_cmake} =================== @tableofcontents @@ -10,10 +10,10 @@ required. If you are building OCCT from bare sources (as in Git repository), or do some changes affecting CDL files, you need to use WOK to re-generate header files -and build scripts / projects. See \ref dev_guides__building__wok for instructions. +and build scripts / projects. See \ref occt_dev_guides__building_wok for instructions. Before building OCCT, you need to install required third-party libraries; see -instructions for your platform in @ref dev_guides__building. +instructions for your platform in @ref occt_dev_guides__building. ## Decide on location of build and install directories. diff --git a/dox/dev_guides/building/code_blocks.md b/dox/dev_guides/building/code_blocks.md index eb39654dfd..9d6fd506be 100644 --- a/dox/dev_guides/building/code_blocks.md +++ b/dox/dev_guides/building/code_blocks.md @@ -1,4 +1,4 @@ -Building with Code::Blocks on Mac OS X {#dev_guides__building__code_blocks} +Building with Code::Blocks on Mac OS X {#occt_dev_guides__building_code_blocks} ====================================== This file describes steps to build OCCT libraries from complete source package @@ -6,10 +6,10 @@ on Mac OS X with Code::Blocks. If you are building OCCT from bare sources (as in Git repository), or do some changes affecting CDL files, you need to use WOK to re-generate header files -and build scripts / projects. See \ref dev_guides__building__wok for instructions. +and build scripts / projects. See \ref occt_dev_guides__building_wok for instructions. Before building OCCT, you need to install required third-party libraries; see -paragraph 1 of \ref dev_guides__building for details. +paragraph 1 of \ref occt_dev_guides__building for details. 1. Add paths to the mandatory 3rd-party products (Tcl/Tk and FreeType) in file custom.sh located in \. For this: diff --git a/dox/dev_guides/building/msvc.md b/dox/dev_guides/building/msvc.md index 8c9fde71f1..2f9de9c63f 100644 --- a/dox/dev_guides/building/msvc.md +++ b/dox/dev_guides/building/msvc.md @@ -1,4 +1,4 @@ -Building with MS Visual C++ {#dev_guides__building__msvc} +Building with MS Visual C++ {#occt_dev_guides__building_msvc} =========================== This file describes steps to build OCCT libraries from complete source @@ -6,10 +6,10 @@ archive on Windows with MS Visual C++. If you are building OCCT from bare sources (as in Git repository), or do some changes affecting CDL files, you need to use WOK to re-generate header files -and build scripts / projects. See \ref dev_guides__building__wok for instructions. +and build scripts / projects. See \ref occt_dev_guides__building_wok for instructions. Before building OCCT, you need to install required third-party libraries; see -paragraph 1 of \ref dev_guides__building for instructions. +paragraph 1 of \ref occt_dev_guides__building for instructions. 1. Edit file custom.bat to define environment: diff --git a/dox/dev_guides/building/wok/wok.md b/dox/dev_guides/building/wok/wok.md index 194a0d080d..1b44bc1c54 100644 --- a/dox/dev_guides/building/wok/wok.md +++ b/dox/dev_guides/building/wok/wok.md @@ -1,11 +1,11 @@ -Using WOK {#dev_guides__building__wok} +Using WOK {#occt_dev_guides__building_wok} ========= @tableofcontents -\ref dev_guides__wok "WOK" is a legacy build environment for Open CASCADE Technology. +\ref occt_dev_guides__wok "WOK" is a legacy build environment for Open CASCADE Technology. It is required for generation of header files for classes defined with -@ref dev_guides__cdl "CDL" ("Cascade Definition Language"). +@ref occt_dev_guides__cdl "CDL" ("Cascade Definition Language"). Also tools for generation of project files for other build systems, and OCCT documentation, are integrated to WOK. diff --git a/dox/dev_guides/building/xcode.md b/dox/dev_guides/building/xcode.md index 5e9784429e..f60d1ffbfb 100644 --- a/dox/dev_guides/building/xcode.md +++ b/dox/dev_guides/building/xcode.md @@ -1,4 +1,4 @@ -Building with Xcode {#dev_guides__building__xcode} +Building with Xcode {#occt_dev_guides__building_xcode} =================== This file describes steps to build OCCT libraries from complete source package @@ -6,10 +6,10 @@ on Mac OS X with Xcode. If you are building OCCT from bare sources (as in Git repository), or do some changes affecting CDL files, you need to use WOK to re-generate header files -and build scripts / projects. See \ref dev_guides__building__wok for instructions. +and build scripts / projects. See \ref occt_dev_guides__building_wok for instructions. Before building OCCT, you need to install required third-party libraries; see -paragraph 1 of \ref dev_guides__building for details. +paragraph 1 of \ref occt_dev_guides__building for details. 1. Add paths to the mandatory 3rd-party products (Tcl/Tk and FreeType) in file custom.sh located in \. For this: diff --git a/dox/dev_guides/cdl/cdl.md b/dox/dev_guides/cdl/cdl.md index a54a4be222..412c9a8b0b 100644 --- a/dox/dev_guides/cdl/cdl.md +++ b/dox/dev_guides/cdl/cdl.md @@ -1,4 +1,4 @@ - Component Definition Language (CDL) {#dev_guides__cdl} + Component Definition Language (CDL) {#occt_dev_guides__cdl} ============================== @tableofcontents diff --git a/dox/dev_guides/contribution/coding_rules.md b/dox/dev_guides/contribution/coding_rules.md index 5ade76fb47..3f85bec2d8 100644 --- a/dox/dev_guides/contribution/coding_rules.md +++ b/dox/dev_guides/contribution/coding_rules.md @@ -1,4 +1,4 @@ -Coding Rules {#dev_guides__coding_rules} +Coding Rules {#occt_dev_guides__coding_rules} ====================================== @tableofcontents @@ -238,7 +238,7 @@ Prefer C++ style comments in C++ sources. ### Commenting out unused code -Delete unused code instead of commenting it or using #define. +Delete unused code instead of commenting it or using \#define. ### Indentation in sources [MANDATORY] @@ -541,7 +541,7 @@ Use *private* fields if future extensions should be disabled. ### Constants and inlines over defines [MANDATORY] -Use constant variables (const) and inline functions instead of defines (#define). +Use constant variables (const) and inline functions instead of defines (\#define). ### Avoid explicit numerical values [MANDATORY] diff --git a/dox/dev_guides/contribution_workflow/contribution_workflow.md b/dox/dev_guides/contribution_workflow/contribution_workflow.md index d8bb29d876..5e0d6b2067 100644 --- a/dox/dev_guides/contribution_workflow/contribution_workflow.md +++ b/dox/dev_guides/contribution_workflow/contribution_workflow.md @@ -1,4 +1,4 @@ -Contribution Workflow {#dev_guides__contribution_workflow} +Contribution Workflow {#occt_dev_guides__contribution_workflow} ==================================== @tableofcontents diff --git a/dox/dev_guides/debug/debug.md b/dox/dev_guides/debug/debug.md index 7c9c12914f..de84bfb99a 100644 --- a/dox/dev_guides/debug/debug.md +++ b/dox/dev_guides/debug/debug.md @@ -1,4 +1,4 @@ -Debugging tools and hints {#dev_guides__debug} +Debugging tools and hints {#occt_dev_guides__debug} ========================= @tableofcontents @@ -27,7 +27,7 @@ Note that all these functions accept pointer to variable as void* to allo @subsection occt_debug_call_draw Interacting with DRAW -Open CASCADE Test Harness or @ref user_guides__test_harness "DRAW" provides an extensive set of tools for inspection and analysis of OCCT shapes and geometric objects and is mostly used as environment for prototyping and debugging OCCT-based algorithms. +Open CASCADE Test Harness or @ref occt_user_guides__test_harness "DRAW" provides an extensive set of tools for inspection and analysis of OCCT shapes and geometric objects and is mostly used as environment for prototyping and debugging OCCT-based algorithms. In some cases the objects to be inspected are available in DRAW as results of DRAW commands. In other cases, however, it is necessary to inspect intermediate objects created by the debugged algorithm. To support this, DRAW provides a set of commands allowing the developer to store intermediate objects directly from the debugger stopped at some point during the program execution (usually at a breakpoint). diff --git a/dox/dev_guides/dev_guides.md b/dox/dev_guides/dev_guides.md index e8d5880a6f..f35fff8130 100644 --- a/dox/dev_guides/dev_guides.md +++ b/dox/dev_guides/dev_guides.md @@ -3,16 +3,16 @@ The following documents provide information on OCCT building, development and testing: -* @subpage dev_guides__building "Building OCCT from sources" -* @subpage dev_guides__documentation "Documentation system" -* @subpage dev_guides__coding_rules "Coding Rules" -* @subpage dev_guides__contribution_workflow "Contribution Workflow" -* @subpage dev_guides__git_guide "Guide to installing and using Git for OCCT development" -* @subpage dev_guides__tests "Automatic Testing system" -* @subpage dev_guides__debug "Debugging tools and hints" +* @subpage occt_dev_guides__building "Building OCCT from sources" +* @subpage occt_dev_guides__documentation "Documentation system" +* @subpage occt_dev_guides__coding_rules "Coding Rules" +* @subpage occt_dev_guides__contribution_workflow "Contribution Workflow" +* @subpage occt_dev_guides__git_guide "Guide to installing and using Git for OCCT development" +* @subpage occt_dev_guides__tests "Automatic Testing system" +* @subpage occt_dev_guides__debug "Debugging tools and hints" Two other documents provide details on obsolete technologies used by OCCT, to be removed in future releases: -* @subpage dev_guides__wok "Workshop Organization Kit (WOK)" -* @subpage dev_guides__cdl "Component Definition Language (CDL)" +* @subpage occt_dev_guides__wok "Workshop Organization Kit (WOK)" +* @subpage occt_dev_guides__cdl "Component Definition Language (CDL)" diff --git a/dox/dev_guides/documentation/documentation.md b/dox/dev_guides/documentation/documentation.md index ceebd33dd5..f0749fa35b 100644 --- a/dox/dev_guides/documentation/documentation.md +++ b/dox/dev_guides/documentation/documentation.md @@ -1,4 +1,4 @@ - Documentation System {#dev_guides__documentation} + Documentation System {#occt_dev_guides__documentation} ====================== @tableofcontents @@ -40,40 +40,52 @@ See \ref OCCT_DM_SECTION_A_9 for more details on inserting mathematical expressi @section OCCT_DM_SECTION_2_1 Documentation Generation -Run *gendoc.bat* from OCCT directory to generate all documents defined in *FILES.txt*: +Run command *gendoc* from command prompt (with OCCT directory as current one) to generate OCCT documentation. +The synopsis is: -*gendoc.bat* can be started with the following options: + gendoc \[-h\] {-refman|-overview} \[-html|-pdf|-chm\] \[-m=|-ug=\] \[-v\] \[-s=\] \[-mathjax=\] + +Here the options are: - * -html : Generates HTML files (cannot be used with -pdf); - * -pdf : Generates PDF files (cannot be used with -html); - * -m=\ : Specifies the list of documents to generate. If it is not specified, all files mentioned in *FILES.txt* are processed; - * -l=\ : Specifies the output document title; - * -mathjax=\ : Specifies the path to a non-default location of MathJAX; - * -h : Prints a help message; - * -v : Toggles the Verbose mode (info on all script actions is shown). +* Choice of documentation to be generated: + * -overview: To generate Overview and User Guides (cannot be used with -refman) + * -refman: To generate class Reference Manual (cannot be used with -overview) -If you run the command without arguments (like in the example above) it will generate HTML documentation for all documents defined in *FILES.txt*. +* Choice of output format: + * -html: To generate HTML files (default, cannot be used with -pdf or -chm) + * -pdf: To generate PDF files (cannot be used with -refman, -html, or -chm) + * -chm: To generate CHM files (cannot be used with -html or -pdf) + +* Additional options: + * -m=\: List of OCCT modules (separated with comma), for generation of Reference Manual + * -ug=\: List of MarkDown documents (separated with comma), to use for generation of Overview / User Guides + * -mathjax=\: To use local or alternative copy of MathJax + * -s=\: Specifies the Search mode of HTML documents; can be: none | local | server | external + * -h: Prints this help message + * -v: Enables more verbose output **Note** -* In case of a PDF output the utility generates a separate PDF file for each document; -* In case of an HTML output the utility generates a common Table of contents containing references to all documents. +* In case of PDF output the utility generates a separate PDF file for each document; +* In case of HTML output the utility generates a common Table of contents containing references to all documents. +* In case of CHM output single CHM file is generated + +**Examples** To generate the output for a specific document specify the path to the corresponding MarkDown file (paths relative to *dox* sub-folder can be given), for instance: ~~~~ - % gendoc.bat -html -m=dev_guides/documentation/documentation.md + > gendoc -overview -ug=dev_guides/documentation/documentation.md ~~~~ -Multiple files can be separated with commas: +To generate Reference Manual for the whole Open CASCADE Technology library, run: ~~~~ - % gendoc.bat -html -m=MD_FILE_1,MD_FILE_2 + > gendoc -refman ~~~~ -Use quotes to specify an article name with -l option, which helps to prevent incorrect interpretation of white spaces: - +To generate Reference Manual for Foundation Classes and Modeling Data modules only, with search option, run: ~~~~ - % gendoc.bat -pdf -m=MD_FILE_1 -l="Label of MD_FILE_1 document" + > gendoc -refman -m=FoundationClasses,ModelingData,ModelingAlgorithms -s=local ~~~~ @section OCCT_DM_SECTION_3 Documentation Conventions diff --git a/dox/dev_guides/git_guide/git_guide.md b/dox/dev_guides/git_guide/git_guide.md index 03739bd356..7a77d3285f 100644 --- a/dox/dev_guides/git_guide/git_guide.md +++ b/dox/dev_guides/git_guide/git_guide.md @@ -1,4 +1,4 @@ -Guide to installing and using Git for OCCT development {#dev_guides__git_guide} +Guide to installing and using Git for OCCT development {#occt_dev_guides__git_guide} ================================= @tableofcontents @@ -307,7 +307,7 @@ Click on that tab, then click **Add a public key**, and paste the text of the pu > git clone gitolite@git.dev.opencascade.org:occt ~~~~~ - where is the path to the new folder which will be created for the repository. + where \ is the path to the new folder which will be created for the repository. * In TortoiseGit: create a new folder, open it and right-click in the Explorer window, then choose **Git Clone** in the context menu: diff --git a/dox/dev_guides/tests/tests.md b/dox/dev_guides/tests/tests.md index 5298224ffb..3406118639 100644 --- a/dox/dev_guides/tests/tests.md +++ b/dox/dev_guides/tests/tests.md @@ -1,4 +1,4 @@ - Automated Testing System {#dev_guides__tests} + Automated Testing System {#occt_dev_guides__tests} ====================================== @tableofcontents @@ -11,7 +11,7 @@ Reading the Introduction is sufficient for OCCT developers to use the test syste @subsection testmanual_1_1 Basic Information -OCCT automatic testing system is organized around DRAW Test Harness @ref user_guides__test_harness "DRAW Test Harness", a console application based on Tcl (a scripting language) interpreter extended by OCCT-related commands. +OCCT automatic testing system is organized around DRAW Test Harness @ref occt_user_guides__test_harness "DRAW Test Harness", a console application based on Tcl (a scripting language) interpreter extended by OCCT-related commands. Standard OCCT tests are included with OCCT sources and are located in subdirectory *tests* of the OCCT root folder. Other test folders can be included in the test system, e.g. for testing applications based on OCCT. @@ -631,12 +631,12 @@ testdiff dir1 dir2 [groupname [gridname]] [options...] Here *dir1* and *dir2* are directories containing logs of two test runs. Possible options are: -* -save - saves the resulting log in a specified file ($dir1/diff-$dir2.log by default). HTML log is saved with the same name and extension .html; +* -save \ - saves the resulting log in a specified file ($dir1/diff-$dir2.log by default). HTML log is saved with the same name and extension .html; * -status {same|ok|all} - allows filtering compared cases by their status: * *same* - only cases with same status are compared (default); * *ok* - only cases with OK status in both logs are compared; * *all* - results are compared regardless of status; -* -verbose - defines the scope of output data: +* -verbose \ - defines the scope of output data: * 1 - outputs only differences; * 2 - additionally outputs the list of logs and directories present in one of directories only; * 3 - (by default) additionally outputs progress messages; diff --git a/dox/dev_guides/wok/wok.md b/dox/dev_guides/wok/wok.md index 8713dddf4f..dd0d0f7c0b 100644 --- a/dox/dev_guides/wok/wok.md +++ b/dox/dev_guides/wok/wok.md @@ -1,4 +1,4 @@ -Workshop Organisation Kit {#dev_guides__wok} +Workshop Organisation Kit {#occt_dev_guides__wok} ========================= @tableofcontents @@ -10,7 +10,7 @@ build system. This use is outdated, and WOK is to be removed in one of future releases of OCCT. Currently only small subset of WOK capabilities described in this document -are actually necessary for building OCCT. See @ref dev_guides__building__wok +are actually necessary for building OCCT. See @ref occt_dev_guides__building_wok for more practical guide. @section occt_wok_1_ Introduction Glossary @@ -96,13 +96,14 @@ interface (i). No description of the source files is needed. There is a single s * jni (j). No description of the source files is needed. There is a single source file: *jni.cdl*. * toolkit (t) The description is given by the file called PACKAGES which is stored in the unit’s src directory. FILES must also exist in this directory, and must include PACKAGES in its list of files. * delivery (d) The description is given by two files stored in the unit’s src directory: FILES and a file called COMPONENTS. FILES must include COMPONENTS in its list of files. -* resource (r) A resource unit is used in a delivery. FILES contains a list of the unit’s files, one per line in the following format: *atype:::afilename* Here, *filename* is the name of a file, which the compiler will look for in the src directory of the unit, and *atype* is a WOK type. To display a list of all available WOK types, use the command: *wokinfo -T*. +* resource (r) A resource unit is used in a delivery. FILES contains a list of the unit’s files, one per line in the following format: *atype\:\:\:afilename* Here, *filename* is the name of a file, which the compiler will look for in the src directory of the unit, and *atype* is a WOK type. To display a list of all available WOK types, use the command: *wokinfo -T*. #### Derived files Derived files created by compilation are automatically placed in the derived section of the development unit. These may be executable files or archives of compilation results. @subsubsection occt_wok_2_1_3 Package + A package is a development unit that defines a set of classes, which share a number of common features such as similar data structure or a set of complementary algorithmic services. Packages help to manage creation and the use of large hierarchies of software components. To create a package, you write a .cdl file describing it in the src directory of the package development unit. The description includes classes and global methods, which comprise it. Each class is also described in a separate .cdl file. The package .cdl file also lists the packages used in the specification of its classes and methods. C++ implementation files are also stored in the src subdirectory of the package development unit. These implementation files are: @@ -335,21 +336,21 @@ These roots are defined in the workbench definition file *MyWorkbench.edl* as th @subsubsection occt_wok_2_2_2 Directories Under each root, a hierarchy of directories allows to store various files. * Under the Home root are found: - * *work*, the private workbench directory reserved for the developer - * *Adm*, the directory reserved for administration files. + * *work*, the private workbench directory reserved for the developer + * *Adm*, the directory reserved for administration files. * Src contains: - * *src/MyUD*, the directory containing the source files of the development unit MyUD. + * *src/MyUD*, the directory containing the source files of the development unit MyUD. * DBMS contains: - * *inc*, containing the public header files of the workbench UDs - * *drv/MyUD*, containing the private extracted files of MyUD - * *drv/MyUD/.adm*, containing the administration files dependent on the extraction profile - * *drv/MyUD/.tmp*, containing the temporary files dependent on the extraction profile. + * *inc*, containing the public header files of the workbench UDs + * *drv/MyUD*, containing the private extracted files of MyUD + * *drv/MyUD/.adm*, containing the administration files dependent on the extraction profile + * *drv/MyUD/.tmp*, containing the temporary files dependent on the extraction profile. * DBMS_Station contains: - * */lib* with all the libraries produced in the workbench - * */bin* with all the binaries produced in the workbench - * */MyUD* with all the station dependent files which are private to the development unit such as objects - * */MyUD/.adm* with all the station dependent administration files - * */MyUD/.tmp* with all the temporary files constructed in the development unit. + * *\/lib* with all the libraries produced in the workbench + * *\/bin* with all the binaries produced in the workbench + * *\/MyUD* with all the station dependent files which are private to the development unit such as objects + * *\/MyUD/.adm* with all the station dependent administration files + * *\/MyUD/.tmp* with all the temporary files constructed in the development unit. @image html /dev_guides/wok/images/wok_image011.png "Structure of the workbench Mywb" @@ -441,7 +442,7 @@ If you don’t want to work in a workshop already present in the factory, you ca ~~~~~ This creates the new workshop **MyWorkshop** in the current factory. To create the same workshop in a different factory use the syntax below: ~~~~~ -> screate –d +> screate –d ~~~~~ When you create a new workshop, it is empty. @@ -537,8 +538,8 @@ You will need to use an editor to implement these methods in C++. To compile the package, use the command: ~~~~~ - > umake -o obj -~~~~~ + > umake -o obj +~~~~~ If you do not specify a package, the current development unit is compiled. #### Sample Construction of a Package @@ -546,20 +547,20 @@ If you do not specify a package, the current development unit is compiled. In the following example a workbench named **MyWb** is created as a child of an existing workbench **Topo**. MyWb is used for working on the package **MyPack**. Commands preceded by an asterisk below are used only once per session: 1. Create the MyWb workbench as a child of Topo. ~~~~~ - > wcreate MyWb -f Topo -d + > wcreate MyWb -f Topo -d ~~~~~ 2. Create MyPack in MyWb. ~~~~~ - > ucreate MyPack     + > ucreate MyPack     ~~~~~ 3. Move to the source directory of MyPack. ~~~~~ - > wokcd MyPack + > wokcd MyPack ~~~~~ 4. Edit the source files (MyPack.cdl etc.). You do this outside tcl, using the editor of your choice. 5. Start the extraction of MyPack. ~~~~~ -  > umake -e xcpp +  > umake -e xcpp ~~~~~ 6. Generate the .cxx templates for MyPack: MyPack.cxx.template ~~~~~ @@ -572,57 +573,57 @@ In the following example a workbench named **MyWb** is created as a child of an #### Package Files * Primary Files for a Package - + .cdl Primary package file. - + _.cdl Primary class file. + + \.cdl Primary package file. + + \_\.cdl Primary class file. * C++ Files for a Package - + .cxx Primary package source file. - + _[1..9[0..9]*].cxx Secondary package source files. - + .lxx Inline package methods source file. - + .pxx Private instructions source file. + + \.cxx Primary package source file. + + \_[1..9[0..9]*].cxx Secondary package source files. + + \.lxx Inline package methods source file. + + \.pxx Private instructions source file. * C++ Files for a Class - + _.cxx Primary class source file. - + __[1..9[0..9]*].cxx + + \_\.cxx Primary class source file. + + \_\_[1..9[0..9]*].cxx * Secondary class source files. - + _.gxx Generic class methods source file. This is an alternative to the .cxx file(s), you do not have both. - + _.lxx Inline methods source file. - + _.pxx Private instructions source file. + + \_\.gxx Generic class methods source file. This is an alternative to the .cxx file(s), you do not have both. + + \_\.lxx Inline methods source file. + + \_\.pxx Private instructions source file. * Derived C++ Files for a Package - + .hxx User header file. - + .ixx User header file included in .cxx. - + .jxx User header file included in _[1-9].cxx. + + \.hxx User header file. + + \.ixx User header file included in \.cxx. + + \.jxx User header file included in \_[1-9].cxx. * Derived C++ files for a class - + _.hxx User header file. - + _.ixx User header file included in _.cxx. - + _.jxx User header file in __[1..9[0..9]*].cxx. - + Handle__.hxx Persistent or Transient class header file. - + __0.cxx For instantiated classes. + + \_\.hxx User header file. + + \_\.ixx User header file included in \_\.cxx. + + \_\.jxx User header file in \_\_[1..9[0..9]*].cxx. + + Handle_\_\.hxx Persistent or Transient class header file. + + \_\_0.cxx For instantiated classes. Umake Steps for a Package ------------------------- The umake steps for development units of package type are explained below. -* *src* Processes the file *MyPackage.cdl* to generate a list of all the CDL files in the development unit. Processes FILES to list source files. -* *xcpp.fill* Compiles the internal data structure to prepare for subsequent extractions. -* *xcpp.src* Lists the source files (.cxx, .gxx, .lxx) deduced from the CDL files. -* *xcpp.header* Extracts header files for the classes in the development unit. +* *src* Processes the file *MyPackage.cdl* to generate a list of all the CDL files in the development unit. Processes FILES to list source files. +* *xcpp.fill* Compiles the internal data structure to prepare for subsequent extractions. +* *xcpp.src* Lists the source files (.cxx, .gxx, .lxx) deduced from the CDL files. +* *xcpp.header* Extracts header files for the classes in the development unit. * *xcpp.template* Extracts a template for implementation of methods. (Hidden step.) -* *obj.inc*     Based on the list of source files generated by the src and xcpp.src steps, this step publishes the include files for the development unit so that other units can use them. -* *obj.cgen* Processes the source files to generate code. -* *obj.comp*   Compiles each file that can be compiled. -* *obj.idep*     Generates dependency information for the unit. This comprises: - + Includes performed by unit compilation (Unit.MakeState) - + Implementation dependencies in terms of the unit suppliers (Unit.ImplDep) -* *obj.lib*    Generates the shared library for the development unit. +* *obj.inc*     Based on the list of source files generated by the src and xcpp.src steps, this step publishes the include files for the development unit so that other units can use them. +* *obj.cgen* Processes the source files to generate code. +* *obj.comp*   Compiles each file that can be compiled. +* *obj.idep*     Generates dependency information for the unit. This comprises: + + Includes performed by unit compilation (Unit.MakeState) + + Implementation dependencies in terms of the unit suppliers (Unit.ImplDep) +* *obj.lib*    Generates the shared library for the development unit. @subsubsection occt_wok_3_4_2 Creating a Nocdlpack If your executable requires the use of a nocdlpack, create a development unit of nocdlpack type and move to its structure using the commands below: ~~~~~ - > ucreate -n - > wokcd + > ucreate -n + > wokcd ~~~~~ Use an editor to write *FILES*, which is a nomenclature file for a nocdlpack. This file must list all the C, C++, Fortran, lex, and yacc sourcs files (one per line). Build the nocdlpack using the following command: ~~~~~ - > umake [] + > umake [] ~~~~~ **Note** that a nocdlpack unit is not intended to perform tests. Use an executable unit instead. @@ -648,14 +649,14 @@ In the following example a nocdlpack *MyNocdlpack*, is created. Commands precede #### Umake Steps for a Nocdlpack The *umake* steps for development units of *nocdlpack* type are explained below. -* *src*   Processes FILES to list source files. -* *obj.cgen* Processes the source files to generate code. -* *obj.inc* Based on the list of source files, this step publishes the header files for the unit so that other units can use them. -* *obj.comp* Compiles each file that can be compiled. -* *obj.idep* Generates dependency information for the unit. This comprises: - + Includes performed by unit compilation. (Unit.MakeState) - + Implementation dependencies in terms of the unit suppliers. (Unit.ImplDep) -* *obj.lib* Generates the shared library for the unit. +* *src*   Processes FILES to list source files. +* *obj.cgen* Processes the source files to generate code. +* *obj.inc* Based on the list of source files, this step publishes the header files for the unit so that other units can use them. +* *obj.comp* Compiles each file that can be compiled. +* *obj.idep* Generates dependency information for the unit. This comprises: + + Includes performed by unit compilation. (Unit.MakeState) + + Implementation dependencies in terms of the unit suppliers. (Unit.ImplDep) +* *obj.lib* Generates the shared library for the unit. @subsubsection occt_wok_3_3_3 Creating a Schema If the application, which you intend to build, stores data in a file, you need to define a schema for the persistent data types that are known. @@ -667,12 +668,12 @@ You create a schema and go to its root directory using the commands: ~~~~~ Using the editor of your choice, write a .cdl file to define the schema. This schema file lists all the packages that contain persistent data types used in the implementation of your application. It has the following format: ~~~~~ - schema MySchema - is + schema MySchema + is class from ; - end; + end; ~~~~~ - + #### Building a Schema Compile and check the coherence of the CDL specification for the schema: @@ -705,25 +706,25 @@ In the following example the schema *MySchema* is created. It contains all the s 3. Edit the source file MySchema.cdl. You do this outside tcl, using the editor of your choice. 4. Derive implementation files. ~~~~~ - > umake -e xcpp.sch + > umake -e xcpp.sch ~~~~~ 5. Derive application schema files. ~~~~~ - > umake -o xcpp.ossg + > umake -o xcpp.ossg ~~~~~ 6. Compile the schema. ~~~~~ - > umake -o obj + > umake -o obj ~~~~~ #### Schema Files * Primary Files for a Schema - + *.cdl* Primary schema file. + + *\.cdl* Primary schema file. * Derived C++ Files for a Schema - + *.hxx* User header files. - + *.cxx* Schema implementation files. - + *.cxx* Schema implementation files. + + *\.hxx* User header files. + + *\.cxx* Schema implementation files. + + *\.cxx* Schema implementation files. #### Umake Steps for a Schema @@ -744,21 +745,21 @@ To make an executable from one or more of the packages, which you have created, Refer to the **CDL User’s Guide** for full details. A simple example is given below. ~~~~~ - executable // the executable unit + executable // the executable unit is - executable myexec // the binary file + executable myexec // the binary file uses Tcl_Lib as external is - myexec; // the C++ file + myexec; // the C++ file end; // several binaries can be specified in one .cdl file. executable myex2 is - myex2; + myex2; end; - end; -~~~~~ - + end; +~~~~~ + Write the C++ file(s). For the example above you write two files: *myexec.cxx* and *myex2.cxx*. #### Building the Executable @@ -770,29 +771,29 @@ To build the executable, use the command *umake* In the following example an executable, *MyExec*, is created in the workbench *MyWb*. Commands preceded by an asterisk below are used only once per session: 1. \*Create MyExec in MyWb. ~~~~~ - > ucreate -x MyExec + > ucreate -x MyExec ~~~~~ 2. Move to the source directory of *MyExec*. ~~~~~ - > wokcd MyExec -~~~~~ + > wokcd MyExec +~~~~~ 3. Edit the cdl source file *MyExec.cdl*. You do this outside tcl, using the editor of your choice. 4. Edit the C++ files *AnExe.cxx*, etc. You do this outside tcl, using the editor of your choice. 5. Build MyExec. ~~~~~ - > umake -~~~~~ + > umake +~~~~~ 6. Run the executable file. ~~~~~ - > wokcd -PLib - > MyExec + > wokcd -PLib + > MyExec ~~~~~ #### Executable Files -| .cdl | primary executable file | -| .cxx | Source C++ file | -| _[1-9].cxx | Other source C++ files | +| \.cdl | Primary executable file | +| \.cxx | Source C++ file | +| \_[1-9].cxx | Other source C++ files | #### Umake Steps for an Executable @@ -812,16 +813,16 @@ To test an executable, you create an executable development unit and move to its When you write the .cdl file for your test executable, specify the packages to test, for example: ~~~~~ executable MyTest // the executable unit - is + is executable mytest1 // the binary file is - mytest1; //the C++ file + mytest1; //the C++ file end; // several binaries can be specified in one .cdl file. executable mytest2 is - mytest2; + mytest2; end; - end; + end; ~~~~~ Write the C++ test file(s), in the example, *mytest1.cxx* and *mytest2.cxx*. #### Building the Executable @@ -879,8 +880,8 @@ source /adv_22/WOK/BAG/KERNEL-K1-2-WOK/adm/Kernel.csh You create and enter a toolkit development unit using the following commands: ~~~~~ - > ucreate -t - > wokcd + > ucreate -t + > wokcd ~~~~~ #### Write the Nomenclature File for the Toolkit @@ -947,7 +948,7 @@ When executables are compiled, a TOOLKITS file is used to determine which toolki Toolkit substitution is performed as follows: 1. MyEngine uses A, B and C; -2. The toolkit TK provides A and D; D uses E; +2. The toolkit TK provides A and D; D uses E; 3. Compilation of *MyEngine* includes TK, B C and E. Here, for simplicity, assume that additional toolkits are not substituted for B, C and E. @@ -976,7 +977,7 @@ Note that keywords and default options are shown in bold. | **Engine** | MyEng **[CDL][DYNAMIC][SOURCES]** | | **Schema** | MyShma **[CDL][LIBRARY][SOURCES][DOC]** | | **Toolkit** |MyTk **[LIBRARY][SOURCES]** | -| **Get** | DevelopmentUnitName::Type:::File | +| **Get** | DevelopmentUnitName::Type\:\:\:File | \* Without mention of the version @@ -1022,22 +1023,22 @@ The output of the umake process is a parcel #### Umake Steps for a Delivery Unit The umake steps for development units of type delivery are explained below. -* *src* Processes FILES to list source files. -* *base*     Creates directories, defines the list of units, copies the parcels and the release notes. -* *get.list*        Lists files to get (using Get, Resource). -* *get.copy* Copy the files listed by get.list. -* *cdl.list*    Lists CDL files to copy. -* *cdl.copy*   Copies the files listed by cdl.list. -* *source.list* Lists units from which sources are to be copied. -* *source.build*    Creates a file for sources (in the format: unit.type.Z). -* *inc.list*         Lists includes to copy. -* *inc.copy*   Copies files listed by inc.list. -* *lib.shared* Works out the inputs for building or copying shareable libraries. -* *lib.shared.build* Copies or builds (depending on the platform) the shareable libraries. -* *lib.server.list*   Lists interface files to copy. -* *exec.list*    Lists inputs for executable delivery. -* *exec.build* Creates executable in the parcel. -* *files*   Works out the list of files delivered in the parcel. +* *src* Processes FILES to list source files. +* *base*     Creates directories, defines the list of units, copies the parcels and the release notes. +* *get.list*        Lists files to get (using Get, Resource). +* *get.copy* Copy the files listed by get.list. +* *cdl.list*    Lists CDL files to copy. +* *cdl.copy*   Copies the files listed by cdl.list. +* *source.list* Lists units from which sources are to be copied. +* *source.build*    Creates a file for sources (in the format: unit.type.Z). +* *inc.list*         Lists includes to copy. +* *inc.copy*   Copies files listed by inc.list. +* *lib.shared* Works out the inputs for building or copying shareable libraries. +* *lib.shared.build* Copies or builds (depending on the platform) the shareable libraries. +* *lib.server.list*   Lists interface files to copy. +* *exec.list*    Lists inputs for executable delivery. +* *exec.build* Creates executable in the parcel. +* *files*   Works out the list of files delivered in the parcel. @subsubsection occt_wok_3_8_2 Installing a Parcel You open the root workbench of the workshop where you want to install the parcel using the following command: @@ -1171,26 +1172,26 @@ In the following example a workbench, *MyWb*, is used for working on the jni, *M Primary jni file is *Jni.cdl* Derived Java files for a Jni are: -* _.java - Java source file of the class to be wrapped. -* _.class - Compiled java source file. +* \_\.java - Java source file of the class to be wrapped. +* \_\.class - Compiled java source file. Derived C++ files for a Jni are: -* ___java.h - Include file for the C++ implementation of JNI. -* ___java.cxx - C++ implementation of JNI. +* \_\_\_java.h - Include file for the C++ implementation of JNI. +* \_\_\_java.cxx - C++ implementation of JNI. ### Umake Steps for a Jni The umake steps for development units of type jni are explained below. -* *src*        Processes MyJni.cdl to list the CDL files for the development unit. Processes the FILES file to list source files. +* *src*        Processes MyJni.cdl to list the CDL files for the development unit. Processes the FILES file to list source files. * *xcpp.fill*     Compiles the internal data structure to prepare for subsequent extractions. -* *xcpp.client* Extracts the services declared in included interface unit(s) into Java and creates .java and \*_java.cxx files. -* *xcpp.javac* Compiles .java files into .class files. -* *xcpp.javah* Creates .h header files. +* *xcpp.client* Extracts the services declared in included interface unit(s) into Java and creates .java and \*_java.cxx files. +* *xcpp.javac* Compiles .java files into .class files. +* *xcpp.javah* Creates .h header files. * *obj.comp* Compiles generated C++ files. -* *obj.idep*    Generates dependency information for the unit. -* *exec.libs* Computes full implementation dependency to prepare for linking. -* *exec.tks*    Performs toolkit substitution. -* *exec.link*    Generates the shared library for the development unit. +* *obj.idep*    Generates dependency information for the unit. +* *exec.libs* Computes full implementation dependency to prepare for linking. +* *exec.tks*    Performs toolkit substitution. +* *exec.link*    Generates the shared library for the development unit. @subsection occt_wok_3_11 More Advanced Use @subsubsection occt_wok_3_11_1 Default User Profile @@ -1198,10 +1199,10 @@ There is a default user profile. If you wish to change this profile the command An example profile is given below. ~~~~~ - Info : Profile in : WOK:k1dev:ref - Info : Extractor : DFLT - Info : Compile Mode : Optimized - Info : Station Type : sil + Info : Profile in : WOK:k1dev:ref + Info : Extractor : DFLT + Info : Compile Mode : Optimized + Info : Station Type : sil ~~~~~ @subsubsection occt_wok_3_11_2 Changing Parcel Configuration Parcel configuration rarely needs changes. However, if you do need to modify the list of resources, you can do so by editing the admin parameter file of the factory. This file is found in the admin directory of the factory and is named after the workshop. It has the suffix .edl. Its full name has the following format: @@ -1286,7 +1287,7 @@ CommandName ~~~~~ **Note** a few commands described in this chapter do not completely respect this syntax; for example, *create* and *rm*. -As a rule, where an __ is given as an argument it specifies which entity the command applies to. Where no __ is specified, the command applies to the nearest appropriate entity. The *create* and *rm* commands are notable exceptions: you **must** specify an entity path with these commands. +As a rule, where an _\_ is given as an argument it specifies which entity the command applies to. Where no _\_ is specified, the command applies to the nearest appropriate entity. The *create* and *rm* commands are notable exceptions: you **must** specify an entity path with these commands. @subsection occt_wok_4_2 General Services General services are commands that apply to any entity manipulated by WOK. They are used for: @@ -1303,10 +1304,10 @@ wokcd -P [] Navigates between different WOK entities and changes the current working directory. Without any arguments wokcd lists the current position (the WOK equivalent of ‘pwd’). With an argument, wokcd moves to the specified location. Options: -* __ Moves to the home directory of the entity specified by , i.e. moves to the location given by the parameter: %wokcd _Home. -* _-P []_ Moves to the directory of the entity specified by . i.e. moves to the location given by the parameter: %_. If no entity path is specified, this command moves to the directory of the current entity. +* _\_ Moves to the home directory of the entity specified by \, i.e. moves to the location given by the parameter: %wokcd \_Home. +* _-P \ [\]_ Moves to the \ directory of the entity specified by \. i.e. moves to the location given by the parameter: %\_\. If no entity path is specified, this command moves to the \ directory of the current entity. -Possible values for are: Home, Adm and Src. +Possible values for \ are: Home, Adm and Src. Use the following commands to change directories within a development unit: * **wsrc** To access the source files. * **winc** To access the include files. @@ -1345,9 +1346,9 @@ Closes and reopens all the entities. ~~~~~ wokenv -f -t csh ~~~~~ -Creates the file . This file is a script, which configures a C shell to mirror the current WOK environment. See the Test Environments section for more details. +Creates the file \. This file is a script, which configures a C shell to mirror the current WOK environment. See the Test Environments section for more details. Options: -* -f - Specifies the name of the file to produce. +* -f \ - Specifies the name of the file to produce. * -t csh - Produces a file for configuring a C shell. * -s - Sets up environment variables for application launching. Example @@ -1361,7 +1362,7 @@ Generates the shell script *MyTestEnvScript* to configure a C shell so that it m wokinfo -