diff --git a/README.md b/README.md index 7de28f5370b786dc77fdd3d71db16c0f91a27ba2..7d112307c254f0d6012bca5aed9f882c921e1d42 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,23 @@ # neSmiK -# Bindings +> Noch eine Schicht mehr im Kuchen -## CXX bindings +which translates roughly into: "Una altra capa al pastís" or "Yet another layer in the cake". -How to configure and install: +Its main use case is to provide an interface to annotate code regions. +These annotated regions then can be used with multiple backends to gain insight in application behavior. -1. `cmake .. -DCMAKE_INSTALL_PREFIX= -DBUILD_C_FORTRAN=OFF` -2. `make install` +## Bindings -### How to use +To make neSmiK easily usable, we provide Fortran, C, C++ bindings to the library. + +### CXX bindings ```cpp #include "nesmik/nesmik.hpp" int main() { - nesmik::Init("Default"); + nesmik::Init("ProperlyNested","Default"); // inits the nesmik library nesmik::RegionStart("peter"); nesmik::RegionStart("marie"); @@ -27,51 +29,28 @@ int main() { } ``` -You **must** call `nesmik::Init` exactly once to Init the datastructures before you can use the other functionality. -Also some backends require finalization, so please make sure to also call `finalize` in the end. - -To add it to your code, currently just install it and use something similar to: -`-I/include -L-I/lib -lnesmik` in the compiler options - -## Fortran - -How to configure and install: +### Fortran -1. `cmake .. -DCMAKE_INSTALL_PREFIX= -DBUILD_C_FORTRAN=ON` -2. `make install` - -### How to use +To enable the Fortran module to be built please add `-DBUILD_C_FORTRAN=ON` to the cmake flags. ```fortran program test use nesmik_mod - call Init("Default") + call Init("ProperlyNested","Default") call RegionStart("test") call RegionStop("test") call Finalize() end program test ``` +Please consider having a look into the documentation (which will be available soon) for further details. +## Backends -You **must** call `Init` exactly once to Init the datastructures before you can use the other functionality. -Also some backends require finalization, so please make sure to also call `finalize` in the end. - -To add it to your code, currently just install it and use something similar to: -`gfortran -I.//include .f90 -o /lib/libnesmik_f.a /lib/libnesmik.so` in the compiler of your choice. - - -# Backends - -## DLB - -### Building - -To build the DLB backend please make sure you have `DLB_HOME` set in your enviroment or provide the installation dir of dlb with `-DDLB_DIR` -To configure: `cmake .. -DENABLE_DLB=ON -DCMAKE_INSTALL_PREFIX= -DBUILD_C_FORTRAN=OFF` - -Please note, that you may have to add the DLB location to the library path, but as you probably preload it anyway, this shoule be fine :) - -### Usage - -`nesmik::Init("DLB")` +| Nesting | Backend | Description | +|-------------------|-------------------|----------------------------------------------------------------| +| ProperlyNested | Default | Default Backend, just prints the regions | +| NotProperlyNested | Default | Default Backend, just prints the regions | +| ProperlyNested | Extrae::TypeStack | Extrae backend using different Types for the levels of nesting | +| ProperlyNested | TALP::Tree | DLB-TALP backend printing a tree to visualize the nesting | +| NotProperlyNested | TALP | DLB-TALP backend to register the monitoring regions | diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000000000000000000000000000000000..d0c3cbf1020d5c292abdedf27627c6abe25e2293 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000000000000000000000000000000000000..747ffb7b3033659bdd2d1e6eae41ecb00358a45e --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000000000000000000000000000000000000..336b1fe591eee28bbd85fc35829ce1936caab3ab --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,33 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'nesmik' +copyright = '2024, BEPPP@BSC' +author = 'BEPPP@BSC' +release = '0.0.1' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'sphinx_rtd_theme', +] + + + + +templates_path = ['_templates'] +exclude_patterns = [] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "sphinx_rtd_theme" +html_static_path = ['_static'] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..250579625b030a803ea1877e4366d599719864e2 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,20 @@ +.. nesmik documentation master file, created by + sphinx-quickstart on Wed Jul 3 09:29:57 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to nesmik's documentation! +================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search`