Developers wiki

Developers tools

Doxygen documentation

1. We assume that you have Doxygen installed.

2. Inside your build directory, run: * the make doc command to compile both the mmg2d, mmg3d and the mmgs documentations; * the make mmg2d_doccommand to compile the mmg2d documentation; * the make mmgs_doc command to compile the mmgs documentation; * the make mmg3d_doccommand to compile the mmg3d documentation.

3. The developers documentation is now available: * open up the doc/Doxygen/mmg2d/html/index.html file to see the mmg2d documentation; * open up the doc/Doxygen/mmgs/html/index.html file to see the mmgs documentation; * open up the doc/Doxygen/mmg3d/html/index.html file to see the mmg3d documentation.

Continuous integration tests

Basic use

You can test your mmg's applications by enabling and running the continuous integration tests (we suggest you to run the tests in debug mode, see the Configuration section of the setup guide for more informations on the compilation modes):

cmake -D CMAKE_BUILD_TYPE=Debug -D BUILD_TESTING=ON ..
make
ctest

Advanced use

You can enable or disable some tests using the following CMake's variables:

| Variable name | Object | Authorized values and effects | |----------------------|-----------------------------------|-------------------------|----------------| | MMG2D_CI | enable or disable the mmg2d tests |

ON	enabled
OFF	disabled

| | MMG3D_CI | enable or disable the mmg3d tests |

ON	enabled
OFF	disabled

| | MMGS_CI | enable or disable the mmgs tests |

ON	enabled
OFF	disabled

| | TEST_LIBMMG3D | enable or disable the tests for the mmg3d library |

ON	enabled
OFF	disabled

| | TEST_LIBMMG2D | enable or disable the tests for the mmg2d library |

ON	enabled
OFF	disabled

| | TEST_LIBMMGS | enable or disable the tests for the mmgs library |

ON	enabled
OFF	disabled

|

Example:
The following command configure CTest to run only the mmg3d application and library tests:

cmake -D TEST_LIBMMG3D=ON ..

Project's tree

Project's source tree

The mmg project is organized as follows:

• the cmake folder contains customization files for CMake and CTest:

Subfolder	Contents
cmake/config	configuration files for CTest
cmake/modules	module files for CMake
cmake/supp	file to suppress libSystem Valgrind errors on MacOs
cmake/testing	files listing the continuous integration tests used by CTest

• the doc folder contains files related to the project documentation:

Subfolder	Contents
doc/Doxygen/mmg3d	Doxygen documentation for mmg3d
doc/Doxygen/mmgs	Doxygen documentation for mmgs
doc/Doxygen/mmg2d	Doxygen documentation for mmg2d

• the libexamples directory contains examples to use the mmg libraries. The libexamples/mmg3d subfolder contains the examples related to the mmg3d library, the libexamples/mmg2d subfolder contains the examples related to the mmg2d library, the libexamples/mmgs subfolder contains the examples related to the mmgs library and the libexamples/mmg subfolder contains the examples related to the use of the mmg library (that gathers the three others libraries).

Subfolder	Contents	Additional informations
libexamples/mmg/example0/	basic example of the use of the mmg library for 2d and 3d surface and volume adaptation test cases
libexamples/mmg/example0_fortran/	same basic example but for a Fortran developer
libexamples/mmg2d/adaptation_example0/	two basic examples of the use of the mmg2d library for an adaptation test case	README.md
libexamples/mmg2d/adaptation_example0_fortran/	basic example of the use of the mmg2d library for a Fortran developer	README.md
libexamples/mmg2d/adaptation_example1/	advanced used of the mmg2d library for an adaptation example	README.md
libexamples/mmg2d/squareGeneration_example2/	advanced used of the mmg2d library for a mesh generation test case	README.md
libexamples/mmgs/adaptation_example0/	basic example of the use of the mmgs library for an adaptation test case	README.md
libexamples/mmgs/adaptation_example0_fortran/	same basic example but for a Fortran developer	README.md
libexamples/mmgs/adaptation_example1/	advanced used of the mmgs library for an adaptation example	README.md
libexamples/mmg3d/adaptation_example0/	two basic examples of the use of the mmg3d library for an adaptation test case	README.md
libexamples/mmg3d/adaptation_example0_fortran/	same basic examples but for a Fortran developer	README.md
libexamples/mmg3d/adaptation_example1/	move quickly from a call to the mmg3d4 library to a call to the new mmg3d library (release 5.x.x)	README.md
libexamples/mmg3d/adaptation_example2/	advanced used of the mmg3d library for an adaptation example	README.md
libexamples/mmg3d/IsosurfDiscretization_example0/	basic example of the use of the mmg3d library for a level-set discretization	README.md

• the src folder contains the applications sources:

Subfolder	Contents
src/common	files used by both mmg2d, mmgs and mmg3d
src/mmg	header files for the mmg library
src/mmg2d	files dedicated to the mmg2d application
src/mmgs	files dedicated to the mmgs application
src/mmg3d	files dedicated to the mmg3d application

• the scripts folder contains the project's scripts.

Created directories

• Compiling the project creates some additional directories used to store the produced outputs:

Folder	Contents
bin	created executables
include	library header files
lib	created libraries

Note that the installation step copies the previous directories at the specified installation path.

• Compiling the Doxygen documentation creates subfolders into the doc/doxygen/ directory:

Subfolder	Contents
doc/doxygen/mmg2d/html	mmg2d documentation
doc/doxygen/mmgs/html	mmgs documentation
doc/doxygen/mmg3d/html	mmg3d documentation

Pull requests

mmg is an open source project so your contributions are welcome. You can help us to improve the mmg applications through:

• bug fixes;
• features development.

The steps to contribute to the mmg project are detailed in the next paragraphs.

I/ Read carefully and agree the following paragraph

To see your work included in the project, please:

• ask first before implementing any features;
• do not perform code refactoring;
• adopt our coding conventions:
  • use our indentation convention (2 spaces instead of tabulations);
  • write accurate Doxygen comments (see for example the documentation of the API_functions.c file);
  • write accurate commit messages;
  • run the continuous integration test before opening any pull request.
• agree to license your work under the GNU Lesser General Public License.

II/ Software contribution

To contribute to the mmg software:

• 1. fork the project on GitHub and clone your fork:

git clone https://github.com/<username>/mmg

• 2. checkout the develop branch and assign the original mmg repository to a remote named upstream:

git checkout develop  
git remote add upstream https://github.com/MmgTools/mmg

• 3. get the last changes from branch develop of the upstream in your own develop branch:

git checkout develop  
git pull upstream develop

• 4. create a new branch to develop your feature:

git checkout -b myFeature

• 5. merge the upstream develop branch into your feature branch:

git pull upstream develop

• 6. if you want, you can push your feature branch up to your repository:

git push origin myfeature

• 7. contribute to the code. Don't forget to regularly merge the upstream develop branch into your feature branch:
     git pull upstream develop to avoid painful merge after huge modifications;
• 8. open a pull request with title and detailed description.