OCCT refactoring project

Overall code and build procedure refactoring
Project leader: Frédéric Pons (frpons)
Forum: Refactoring
Mantis issue: #24002
Status: In progress

Overview

When OCCT was created in 1980's, C++ was not as advanced as now. OCCT introduced a specific declaration language, CDL (Cas.Cade Definition Language), to provide features not-yet well supported by C++ compilers at the time, such as smart pointers (Handles), run-time type identification and templates (CDL generics). WOK, which is the OCCT custom build system, provided connection between CDL and C++ compiler, as well as general framework for OCCT development.

By now CDL and WOK have clearly become obsolete and seriously hamper the adoption of OCCT by C++ developers. Hence we aim at getting rid of CDL and WOK, using the features provided by modern C++ language and up-to-date build tools instead.

Our main goal is to make OCCT more suitable for use in modern development environments, by removing obsolete features which require extra effort for maintaining and impede adoption of OCCT by new developers, and providing better compatibility with modern C++ technologies and build tools.

The points to be changed by completion of this project are:

  1. All OCCT classes will be defined in C++ (no CDL).
  2. Build system will rely only on third-party tools (no WOK); all build scripts will be provided with OCCT code.
  3. It will be easier to use OCCT classes in code employing namespaces, templates, STL algorithms, etc.

Overall structure of the OCCT sources (modules, toolkits, packages), naming
conventions (e.g. class or typedef being defined in header file with the same name), and other coding rules will be kept as they are now.

The existing interfaces of the classes will be preserved as much as possible to minimize the changes required in existing code based on OCCT. For the changes which will be necessary we should develop automatic tool to upgrade client code, and provide detailed description of migration procedure.

Agenda

The following steps are planned within this project.

I. Refactor OCCT code

This step has two goals: (a) to decrease amount and improve maintenability of files generated by WOK (to ease future maintenance), and (b) to remove limitations that restrict use of OCCT in modern C++ developments (in particular, improve compatibility with STL).

  1. Minimize amount of OCCT generic classes.

    Generic classes in CDL use C preprocessor macros to instantiate generic code for particular argument types. This is obsolete and inconvenient
    method, requiring separate CXX file for each instance, and breaking association between the types found in the code and actual types used, thus making the code difficult to debug.

    • Some generic classes are not used at all - they will be simply removed
    • Many generic classes are instantiated only once; these will be converted to plain classes
    • Instantiations of generic classes from TCollection will be replaced by equivalent template classes from NCollection package
    • In some cases when generic classes are relatively simple or the same
      mechanism is used on the level of methods and functions (rather than classes), we are going to convert generics to C++ templates
    • Remaining complex cases - generics that have multiple instantiations, nested classes etc. - will be addressed on a case-by-case basis. Some of them can be converted to templates, some will remain in GXX form even in OCCT 7.0.
  2. Exception classes, currently generated by WOK from CDL declarations, will be converted to templates.
  3. Provide STL-compatible interface in OCCT collection classes, so that they can be used in STL algorithms directly. Some algorithms implemented in OCCT can be replaced by STL equivalents.
  4. Revise implementation of OCCT Handle classes and RTTI.

    Handle classes in OCCT implement intrusive smart pointer, with reference counter provided by the base class (Standard_Transient). In comparison with std::shared_ptr<>, more common for C++ programmers, it has both positive and negative features:

    Positive:

    • Intrusive nature allows creating Handles from pointer to object. Though not a good practice, this feature is used in a number of places in OCCT and applications, and breaking this possibility is not desired.
    • Handle does not require allocation of additional block of memory for
      the counter as std::shared_ptr<> does (unless std::make_shared<> is used).
    • Inheritance: each Handle inherits Handle to the base class of its
      type class. This allows Handle objects to be passed by reference where
      Handle to base type is expected, without creation of a copy.
    • Likely better performance in applications due to above features (yet to be confirmed by careful testing).

    Negative:

    • Special effort is needed to define a handle: insertion of macros
      in both header file and CXX code.
    • Handles cannot be used for template classes (except NCollection_Handle
      which is a kind of work-around).
    • Definition of Handles for class defined in namespace is possible, but is tricky and in general does not worth efforts, therefore most of the code using Handles does not use namespaces.
    • No support for weak references (std::weak_ptr<>).

    Our goal in refactoring project is to keep maximal compatibility with existing code of applications using OCCT. Hence, we are going to keep existing approach with intrusive reference counting and inheritance, thus minimizing changes required in the user code and keeping good performance potential.

  5. Refactor or remove old OCCT persistence classes (packages such as PBRep, PColStd, PDF, PDocStd and the corresponding MDF, MDocStd, etc.) to avoid having lots of generated code, difficult to maintain.

    We ask those who use old OCCT persistence to show up; if it is not used we will just remove these classes.

This work will lead to modification of all C++ header and most of source files. C++ derived files generated by WOK, such as .jxx, _0.cxx and .ixx, should be not needed any more.

II. Get rid of WOK and CDL

  1. Before decommissioning, WOK will be modified to support refactoring steps:
    • Generate well formatted HXX files, preserving all documentation comments. Some effort will be needed to check that all comments are passed intact, nothing gets lost. Further corrections in documentation will be done in HXX files.
    • Provide necessary support for use of C++ definitions instead of CDL ones, e.g. for classes operated by Handle as *imported*
    • Avoid generation of files which are not needed any more: "Handle_*.hxx" for transient classes, *.ixx and *.jxx, etc.
  2. When refactoring is ready, CDL will be dropped; HXX and other files currently generated by WOK will be put to sources.
  3. New build system will be put in force, most likely based on CMake, to be developed using experience of SALOME project.

    Note that currently we do not exclude possibility to keep some helper tools implemented in Tcl.

III. Other improvements

Other improvements, even if not currently planned, can be considered later.

The current list of possible candidates is:

  1. Avoid use of OCCT-specific aliases to elementary data types like Standard_Integer, Standard_Character; use plain C++ types instead. This will make OCCT code much easier to deal with for new developers.
  2. OCCT sources can be reformatted using tool like Uncrustify to enforce
    common code formatting style.
  3. Implementations of OCCT strings and collections can be replaced by use of standard C++ equivalents provided by STL (where justified)
  4. Merge LXX files containing implementation of inline functions, to corresponding HXX files, to reduce number of files to be maintained (currently we have 741 LXX file).

Progress

This project has started in June 2013 from elimination of generic classes, and prototyping replacement of Handle and OCCT RTTI by C++ templates.

During 2014 and first half of 2015 we worked on steps of the agenda, and development of improvements listed in sections I and II have been mostly completed by July 2015. Then we will have several rounds of review and testing before the final version can be released as OCCT 7.0, tentatively by the end of 2015.

The entire open source community using and contributing to OCCT is welcome to post ideas, proposals and eventually requirements. For that, please use the dedicated forum sub-section and Mantis issues (the link is at the top of this page).

www.opencascade.com

Copyright 2011-2017
OPEN CASCADE SAS
Contact us