Commit d79a4b0f authored by David Thompson's avatar David Thompson

Extend test timeouts for plugin (contract) tests.

RGG takes time to build and fetching XMS from conan
can also be slow.

Add some documentation on contract tests, and a new
gitattribute style so that section heading markings
are not mistaken for git conflict markers.
parent edada9bc
# Attributes used for formatting.
[attr]our-c-style whitespace=tab-in-indent format.clang-format
[attr]our-py-style whitespace=tab-in-indent format.autopep8
[attr]our-rst-style conflict-marker-size=100
*.cxx our-c-style
*.h our-c-style
......@@ -9,6 +10,8 @@
*.py our-py-style
*.rst our-rst-style
thirdparty/** -format.clang-format -format.autopep8
**/pybind11/* -format.clang-format
......
......@@ -56,7 +56,10 @@ function(smtk_test_plugin test_plugin_file_url)
-DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
-Dsmtk_DIR=${PROJECT_BINARY_DIR}
${response_file}
)
)
# Plugin tests can take a little longer since they need to
# clone a repo and build a project.
set_tests_properties(${test_name} PROPERTIES TIMEOUT 600)
# If on Windows, pass the environment PATH to the test.
if (WIN32)
......
......@@ -202,6 +202,7 @@ if (SMTK_ENABLE_TESTING)
set(SMTK_PLUGIN_CONTRACT_FILE_URLS ""
CACHE STRING "Local CMake file describing plugins as external projects for contract testing.")
# ++ contract-example ++
if (SMTK_ENABLE_PARAVIEW_SUPPORT)
set(local_url_prefix "file://")
if (WIN32)
......@@ -210,6 +211,7 @@ if (SMTK_ENABLE_TESTING)
list(APPEND SMTK_PLUGIN_CONTRACT_FILE_URLS
"${local_url_prefix}${CMAKE_CURRENT_SOURCE_DIR}/CMake/resource-manager-state.cmake")
endif()
# -- contract-example --
set(SMTK_COVERAGE_ENABLED OFF)
if(SMTK_ENABLE_COVERAGE)
......
......@@ -105,7 +105,14 @@ if (SPHINX_FOUND)
userguide/attribute/index.rst
userguide/attribute/file-syntax.rst
userguide/attribute/concepts.rst
userguide/contributing.rst
userguide/contributing/documentation.rst
userguide/contributing/exposing.rst
userguide/contributing/extending.rst
userguide/contributing/index.rst
userguide/contributing/organization.rst
userguide/contributing/style.rst
userguide/contributing/testing.rst
userguide/contributing/todo.rst
userguide/administration.rst
userguide/obtain-build-install.rst
userguide/simulation/index.rst
......
......@@ -3,3 +3,4 @@
- Removed one problematic test, `displayMultiBlockModel-simple`, that used an outdated input file and rendered differently on some dashboard systems.
- Added `knee.ex2` exodus test data, used by ModelBuilder tests for now.
- If we are running tests, don't display the "Your data is modified, save changes?" dialog on exit.
- Plugin (contract) tests now have a timeout of 600 seconds to allow more time for cloning and building a repository.
pyparsing==1.5.7
Pygments==2.2.0
Sphinx==1.6.3
pyparsing==2.0.2
Pygments==2.2.0
actdiag==0.5.4
blockdiag==1.5.3
sphinxcontrib-actdiag==0.7.2
......
.. _smtk-contributing:
********************
Contributing to SMTK
********************
.. role:: cxx(code)
:language: c++
.. role:: cmake(code)
:language: cmake
.. contents::
The first step to contributing to SMTK is to obtain the source code and build it.
The top-level ReadMe.md file in the source code includes instructions for building SMTK.
The rest of this section discusses how the source and documentation are organized
and provides guidelines for how to match the SMTK style.
Source code organization
========================
To a first approximation, SMTK's directory structure mirrors the namespaces used:
classes in the :cxx:`smtk::attribute` namespace are mostly found in the
:file:`smtk/attribute` directory.
Exceptions occur where classes that belong in a namespace depend on third-party libraries
that should not be linked to SMTK's core library.
For example, Qt widgets for attributes are in :file:`smtk/extensions/qt`, not in :file:`smtk/attribute`
because they depend on Qt, which is optional when building SMTK (so that, for instance,
solid modeling kernels like Cubit may be supported without issue).
With that in mind:
* smtk — this directory contains all of the source code for SMTK libraries and tests
* common — source for classes used throughout the smtkCore library
* attribute — source for :ref:`smtk-attribute-sys` in the smtkCore library
* model — source for :ref:`smtk-model-sys` in the smtkCore library
* mesh — source for :ref:`smtk-mesh-sys` in the smtkCore library
* simulation — aids to exporting simulation input decks in the smtkCore library
* io — file and string I/O in the smtkCore library, a mix of XML and JSON
* view — source for providing views of attributes and models in the smtkCore library
* session — source for additional libraries that session solid modeling kernels into SMTK
* extensions — source for additional libraries that expose SMTK to other software
* qt — widgets that allow presentation and editing of SMTK models and attributes
* vtk — VTK_ sources for displaying tessellations of model faces, edges, and vertices
* thirdparty
* cJSON — used to serialize geometric model information
* pugiXML — used to serialize attribute resources
* utilities — scripts to aid in the development of SMTK
Inside :file:`smtk/`, subdirectories, there are :file:`testing/` directories that
hold :file:`python/` and :file:`cxx/` directories for Python and C++ tests, respectively.
Code style
==========
* No tabs or trailing whitespace are allowed.
* Indent blocks by 2 spaces.
* Class names should be camel case, starting with an uppercase.
* Class member variables should start with :cxx:`m_` or :cxx:`s_` for per-instance or class-static variables, respectively.
* Class methods should be camel case starting with a lowercase character (except acronyms which should be all-uppercase).
* Use shared pointers and a static :cxx:`create()` method for classes that own significant storage or must be passed by
reference to their superclass.
Using SMTK from another project
===============================
SMTK generates a file named :file:`SMTKConfig.cmake` that allows other projects to find and use SMTK.
This file is installed to :file:`${CMAKE_INSTALL_PREFIX}/lib/cmake/SMTK/`.
Your project can add SMTK with
.. code:: cmake
find_package(SMTK)
Then, when building your project, set CMake's :cmake:`SMTK_DIR` to the directory containing :file:`SMTKConfig.cmake`.
Extending SMTK
==============
See the tutorials for in-depth guides on how to extend SMTK
in certain obvious directions,
* Writing an attribute resource template file to represent a solver's input format.
* Writing an exporter to support a new solver's input format.
* Adding a new solid-modeling operator
* Bridging SMTK to a new solid-modeling kernel
Documentation style
===================
......@@ -172,16 +78,4 @@ If you are unfamiliar with the documentation packages here, see these links for
.. _Homebrew: http://brew.sh/
.. _Sphinx: http://sphinx-doc.org/
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _VTK: http://vtk.org/
.. _documentation for roles in reStructuredText: http://sphinx-doc.org/markup/inline.html
To-do list
==========
Finally, if you are looking for a way to contribute,
helping with the documentation would be great.
A list of incomplete documentation (or incomplete features)
is below.
You can also look on the SMTK issue tracker for things to do.
.. todolist::
Exposing SMTK for use in external projects
==========================================
SMTK generates a file named :file:`SMTKConfig.cmake` that allows other projects to find and use SMTK.
This file is installed to :file:`${CMAKE_INSTALL_PREFIX}/lib/cmake/SMTK/`.
External projects can add SMTK with
.. code:: cmake
find_package(SMTK)
Then, when building external projects, set CMake's :cmake:`SMTK_DIR` to the directory containing :file:`SMTKConfig.cmake`.
Note that you may point external projects to the top level of an SMTK build directory or
an install tree's :file:`lib/cmake/SMTK` directory; both contain an :file:`SMTKConfig.cmake` file
suitable for use by external projects.
The former is suitable for development, since you may be modifying both SMTK and a project
that depends on it — having to re-install SMTK after each change becomes tedious.
The latter is suitable for creating packages and distributing software.
If you add a new dependency to SMTK, :file:`CMake/smtkConfig.cmake.in` (which is used to create
:file:`SMTKConfig.cmake`) should be configured to find the dependent package so that consumers
of SMTK have access to it without additional work.
If you add a new option to SMTK, it should be exposed in :file:`CMake/Options.h.in`.
Extending SMTK
==============
As with all software, it is important to understand where
functionality you wish to add belongs: in your project,
in SMTK's core library, or in an upstream dependency of SMTK.
The tutorials provide in-depth guides on how to extend SMTK
in certain obvious directions,
* Writing an attribute resource template file to represent a solver's input format.
* Writing an exporter to support a new solver's input format.
* Adding a new solid-modeling operator
* Bridging SMTK to a new solid-modeling kernel
These tasks are all examples of projects that might use SMTK
as a dependency but not alter SMTK itself.
On the other hand, if you are attempting to provide functionality
that (a) does not introduce dependencies on new third-party libraries;
(b) will be useful to most projects that use SMTK; and
(c) cannot be easily be factored into a separate package,
then it may be best to contribute these changes to SMTK itself.
In that case, the rest of this section discusses how SMTK should be
modified and changes submitted for consideration.
.. _smtk-contributing:
--------------------
Contributing to SMTK
--------------------
.. role:: cxx(code)
:language: c++
.. role:: cmake(code)
:language: cmake
.. contents::
The first step to contributing to SMTK is to obtain the source code and build it.
The top-level ReadMe.md file in the source code includes instructions for building SMTK.
The rest of this section discusses how the source and documentation are organized
and provides guidelines for how to match the SMTK style.
.. toctree::
:maxdepth: 3
organization.rst
extending.rst
exposing.rst
style.rst
documentation.rst
testing.rst
todo.rst
Source code organization
========================
To a first approximation, SMTK's directory structure mirrors the namespaces used:
classes in the :cxx:`smtk::attribute` namespace are mostly found in the
:file:`smtk/attribute` directory.
Exceptions occur where classes that belong in a namespace depend on third-party libraries
that should not be linked to SMTK's core library.
For example, Qt widgets for attributes are in :file:`smtk/extensions/qt`, not in :file:`smtk/attribute`
because they depend on Qt, which is optional when building SMTK (so that, for instance,
solid modeling kernels like Cubit may be supported without issue).
With that in mind:
* smtk — this directory contains all of the source code for SMTK libraries and tests
* common — source for classes used throughout the smtkCore library
* resource — :ref:`smtk-resource-sys` defines base resources (files) and components used elsewhere
* attribute — source for :ref:`smtk-attribute-sys` in the smtkCore library
* model — source for :ref:`smtk-model-sys` in the smtkCore library
* mesh — source for :ref:`smtk-mesh-sys` in the smtkCore library
* operation — :ref:`smtk-operation-sys` provides asynchronous operations that act on resources
* simulation — aids to exporting simulation input decks in the smtkCore library
* io — file and string I/O in the smtkCore library, a mix of XML and JSON
* view — source for providing views (user presentations) of resources in the smtkCore library
* session — source for additional libraries that session solid modeling kernels into SMTK
* extensions — source for additional libraries that expose SMTK to other software
* qt — widgets that allow presentation and editing of SMTK models and attributes
* vtk — VTK_ sources for displaying tessellations of model faces, edges, and vertices
* paraview - user interface components that embed SMTK into branded ParaView_ applications
* thirdparty
* cJSON — used to serialize geometric model information
* pugiXML — used to serialize attribute resources
* utilities — scripts to aid in the development of SMTK
Inside :file:`smtk/`, subdirectories, there are :file:`testing/` directories that
hold :file:`python/` and :file:`cxx/` directories for Python and C++ tests, respectively.
These are discussed more in :ref:`smtk-testing-sys`.
.. _VTK: http://vtk.org/
.. _ParaView: http://paraview.org/
Code style
==========
* No tabs or trailing whitespace are allowed.
* Indent blocks by 2 spaces.
* Class names should be camel case, starting with an uppercase.
* Class member variables should start with :cxx:`m_` or :cxx:`s_` for per-instance or class-static variables, respectively.
* Class methods should be camel case starting with a lowercase character (except acronyms which should be all-uppercase).
* Use shared pointers and a static :cxx:`create()` method for classes that own significant storage or must be passed by
reference to their superclass.
Testing
=======
Testing is important to keep SMTK functioning as development continues.
All new functionality added to SMTK should include tests.
When you are preparing to write tests, consider the following
* Unit tests should be present to provide coverage of new classes and methods.
* Integration tests should be present to ensure features work in combination
with one another as intended; these tests should model how users are expected
to exercise SMTK in a typical workflow.
* Regression tests should be added when users discover a problem in functionality
not previously tested and which further development may reintroduce.
* Contract tests should be added for downstream projects (i.e., those which depend
on SMTK) which SMTK should not break through API or behavioral changes.
A contract test works by cloning, building, and testing an external project;
if the external project's tests all succeed, then the contract test succeeds.
Otherwise, the contract test fails.
Contract tests
--------------
Contract tests can be added by appending a URL to the :file:`SMTK_PLUGIN_CONTRACT_FILE_URLS`
CMake variable.
You can see an example of this in SMTK's top-level CMakeLists.txt:
.. literalinclude:: ../../../CMakeLists.txt
:language: cmake
:start-after: # ++ contract-example ++
:end-before: # -- contract-example --
:linenos:
Each URL listed in the CMake variable must be a CMake script;
typically, this script will declare a new project consisting of an external project dependent on SMTK.
.. literalinclude:: ../../../CMake/resource-manager-state.cmake
:language: cmake
:linenos:
When the script is run, the external project's source is downloaded, the project configured, and tests
are run. If they all complete with success, then the contract test succeeds.
This pattern of appending URLs was chosen so that machines used to test merge
requests which happen to have access to closed-source downstream projects could
be configured with additional URLs to contract tests. That way, even closed-source
downstreams can cause test failures in SMTK; this informs developers of SMTK merge
requests that additional work may be required on downstream projects before the
merge can succeed.
To-do list
==========
Finally, if you are looking for a way to contribute,
helping with the documentation would be great.
A list of incomplete documentation (or incomplete features)
is below.
You can also look on the SMTK issue tracker for things to do.
.. todolist::
......@@ -47,7 +47,7 @@ simulation domain.
bindings/index.rst
plugin/index.rst
administration.rst
contributing.rst
contributing/index.rst
.. role:: cxx(code)
:language: c++
.. _smtk-resource-sys:
.. _smtk-operation-sys:
-----------------------
SMTK's Operation System
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment