From ebe48c4ff43dc927ead61548d914b5de3e6252f2 Mon Sep 17 00:00:00 2001 From: Valentin Seitz Date: Wed, 3 Jul 2024 10:23:19 +0200 Subject: [PATCH 1/2] run sphinx-quickstart --- docs/Makefile | 20 ++++++++++++++++++++ docs/make.bat | 35 +++++++++++++++++++++++++++++++++++ docs/source/conf.py | 33 +++++++++++++++++++++++++++++++++ docs/source/index.rst | 20 ++++++++++++++++++++ 4 files changed, 108 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /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 0000000..747ffb7 --- /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 0000000..336b1fe --- /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 0000000..2505796 --- /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` -- GitLab From 40829a5245629bee7a871777f22160872fbb17a1 Mon Sep 17 00:00:00 2001 From: Valentin Seitz Date: Wed, 3 Jul 2024 10:23:26 +0200 Subject: [PATCH 2/2] Update README --- README.md | 63 +++++++++++++++++++------------------------------------ 1 file changed, 21 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 7de28f5..7d11230 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 | -- GitLab