{"id":20048898,"url":"https://github.com/sintef/fortran-stacktrace","last_synced_at":"2025-05-05T10:31:42.907Z","repository":{"id":88354844,"uuid":"486579423","full_name":"SINTEF/fortran-stacktrace","owner":"SINTEF","description":"Generate stacktraces from Fortran","archived":false,"fork":false,"pushed_at":"2022-11-02T19:14:30.000Z","size":214,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-08T21:41:24.790Z","etag":null,"topics":["error-handling","fortran","stacktrace"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SINTEF.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-04-28T12:11:26.000Z","updated_at":"2024-12-24T19:02:07.000Z","dependencies_parsed_at":"2023-09-24T12:18:09.168Z","dependency_job_id":null,"html_url":"https://github.com/SINTEF/fortran-stacktrace","commit_stats":{"total_commits":6,"total_committers":1,"mean_commits":6.0,"dds":0.0,"last_synced_commit":"cbcedd7e96022c793c5c0b1ca2ebaf835e4242a1"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SINTEF%2Ffortran-stacktrace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SINTEF%2Ffortran-stacktrace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SINTEF%2Ffortran-stacktrace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SINTEF%2Ffortran-stacktrace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SINTEF","download_url":"https://codeload.github.com/SINTEF/fortran-stacktrace/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252480515,"owners_count":21754785,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["error-handling","fortran","stacktrace"],"created_at":"2024-11-13T11:47:20.924Z","updated_at":"2025-05-05T10:31:41.843Z","avatar_url":"https://github.com/SINTEF.png","language":"C++","readme":"= Fortran Stacktrace\r\n:imagesdir: doc/\r\n\r\n:repo: SINTEF/fortran-stacktrace\r\n**Generate stacktraces in Fortran**\r\n\r\nimage:https://github.com/{repo}/actions/workflows/built-test.yml/badge.svg[link=\"https://github.com/{repo}/actions/workflows/built-test.yml\"]\r\nimage:https://img.shields.io/github/v/release/{repo}?label=version\u0026sort=semver[link=\"https://github.com/{repo}/releases\"]\r\n\r\nThis library enables generation of stacktraces for Fortran.\r\nIt does so by providing a Fortran wrapper around the C++ library\r\nhttps://github.com/bombela/backward-cpp[backward-cpp].\r\n\r\nIt also integrates with the Fortran\r\nhttps://github.com/SINTEF/fortran-error-handling[error-handling] library in order\r\nto generate errors that includes a stacktrace.\r\nThis means that you can easily make even old legacy code output errors messages like this:\r\n\r\nimage::stacktrace-example.png[]\r\n\r\nThe source code snippets are of course voluntary and only available on a machine\r\nwith access to the source code itself.\r\n\r\n\r\n== Building\r\n\r\nA fairly recent Fortran and C++ compiler is required to build this library.\r\nThe following compilers are known to work:\r\n\r\n- gfortran version 9 or later\r\n- Intel Fortran 2021 or later\r\n\r\nNOTE: Stacktraces are currently not enabled for gcc/gfortran when using MinGW\r\non Windows.\r\nIt seems like backward-cpp should support this, but I haven't figured out how to get it\r\nworking. Pull requests are welcome if anyone wants to have a look at this!\r\n\r\nIn order to get proper stacktraces you also need to *compile your source code with\r\ndebug information*. To do this use the following compiler flags\r\n|===\r\n| Compiler Vendor | Operating System | Compiler flag | Link flag\r\n| GCC             | Linux            | `-g`          |\r\n| Intel           | Linux            | `-g`          |\r\n| Intel           | Windows          | `-Z7`         | `-debug`\r\n|===\r\n\r\nThis will increase the binary size slightly, but contrary to popular belief it should\r\n*not* impact performance of your code!\r\n\r\nOn Linux, you also need to install binutils-dev which contains libbfd:\r\n[source,bash]\r\n----\r\napt-get install binutils-dev # or the equivalent for your distro\r\n----\r\n\r\nFor more information see also the https://github.com/bombela/backward-cpp[backward-cpp]\r\ndocumentation.\r\n\r\n=== CMake\r\n\r\nFirst, enable both Fortran and CXX as languages in your project:\r\n\r\n[source,cmake]\r\n----\r\nproject(\u003cyour project name\u003e LANGUAGES Fortran CXX)\r\n----\r\n\r\nOr:\r\n\r\n[source,cmake]\r\n----\r\nenable_language(\"Fortran\")\r\nenable_language(\"CXX\")\r\n----\r\n\r\nTo use the recommended compiler and link flags you can for example do the following:\r\n\r\n[source,cmake]\r\n----\r\nif(CMAKE_Fortran_COMPILER_ID MATCHES \"GNU\")\r\n    set(CMAKE_Fortran_FLAGS \"-g\")\r\n    if(WIN32)\r\n        set(CMAKE_EXE_LINKER_FLAGS \"-debug\")\r\n    endif(WIN32)\r\nelseif(CMAKE_Fortran_COMPILER_ID MATCHES \"Intel\")\r\n    if(WIN32)\r\n        set(CMAKE_Fortran_FLAGS \"-Z7\")\r\n        set(CMAKE_EXE_LINKER_FLAGS \"-debug\")\r\n    else(WIN32)\r\n        set(CMAKE_Fortran_FLAGS \"-g\")\r\n    endif(WIN32)\r\nendif()\r\n----\r\n\r\nThis example is not complete, but can be used as a starting point.\r\nAdd other compiler flags depending on your project needs.\r\n\r\nThe recommended way of getting the source code for this library when using CMake\r\nis to add it as a dependency using\r\nhttps://github.com/cpm-cmake/CPM.cmake/[CMake Package Manager (CPM)]:\r\n\r\n[source,cmake]\r\n----\r\nCPMAddPackage(\"https://github.com/SINTEF/fortran-stacktrace.git@0.1.0\")\r\ntarget_link_libraries(\u003cyour target\u003e stacktrace)\r\n----\r\n\r\n\r\n=== CMake Without CPM\r\n\r\nIf you don't want to use CPM you can either use\r\nhttps://cmake.org/cmake/help/latest/module/FetchContent.html[FetchContent]\r\nmanually or add this repo as a git submodule to your project. Then in your\r\n`CMakeLists.txt` add it as a subdirectory and use `target_link_libraries` to\r\nlink against `stacktrace`.\r\n\r\nDo however note that this library will still use CPM to add\r\nhttps://github.com/SINTEF/fortran-error-handling[fortran-error-handling]\r\nas its dependency.\r\n\r\n=== Fortran Package Manager (FPM)\r\n\r\nFPM is currently not supported as it is not yet able to compile C++ sources.\r\n\r\n\r\n== Usage\r\n\r\nWARNING: The procedures for loading and displaying a stacktrace is declared as pure\r\n         however they do invoke C++ code which by definition cannot be pure.\r\n         This is possible because the c-bindings are declared pure which is done by\r\n         hand.\r\n         The procedures does not have any side effects, which is the intent for\r\n         of pure procedures in Fortran.\r\n         If you are not comfortable with this way of stretching the definition of\r\n         `pure`, don't use `stacktrace_t` in pure procedures!\r\n\r\nWARNING: As of this writing, the latest gfortran versions has bugs related to\r\n         user defined finalization of derived types. In order to avoid crashes\r\n         like segmentation faults due to this, finalization is currently disabled\r\n         when gfortran is used. As a result there will be a memory leak if a\r\n         loaded `stacktrace_t` is deallocated or goes out of scope.\r\n\r\n=== Error Handling Integration\r\n\r\nIt is possible to make errors created with the\r\nhttps://github.com/SINTEF/fortran-error-handling[fortran-error-handling]\r\nlibrary contain a stacktrace.\r\nTo do this, add the following code near the top of your program,\r\npreferably before any errors may occur:\r\n\r\n[source, Fortran]\r\n----\r\nprogram main\r\n    use error_handling, only: set_error_hook\r\n    use stacktrace_mod, only: stacktrace_error_hook_t\r\n    implicit none\r\n\r\n    call set_error_hook(stacktrace_error_hook_t())\r\n\r\n    ! (...)\r\nend program\r\n----\r\n\r\nFor a complete example, see link:example/error-handling-integration.f90[`error-handling-integration.f90`].\r\n\r\n=== Generating Stacktraces\r\n\r\nTo generate a stacktrace from an arbitrary code location, do the following:\r\n\r\n[source,fortran]\r\n----\r\nuse stacktrace_mod, only: stacktrace_t\r\n\r\ntype(stacktrace_t) :: st\r\ncharacter(len=:), allocatable :: chars\r\n\r\n! Load a stacktrace from this point\r\ncall st%load_here()\r\n\r\n! Convert the stacktrace into character, e.g. for writing to a log file.\r\n! `snippet=.false.` disables snippet generation even when sources are available\r\nchars = st%to_chars(snippet=.false.)\r\nwrite(*,'(a)') chars\r\n----\r\n\r\n== Contributions\r\n\r\nFeel free to submit Feedback, suggestions or any problems in the issue tracker.\r\n\r\n== License and Copyright\r\n\r\nCopyright 2022 SINTEF Ocean AS. All Rights Reserved. MIT License.\r\n\r\nhttps://github.com/bombela/backward-cpp[backward-cpp] is redistributed by this project.\r\nCopyright 2013-2017 Google Inc. All Rights Reserved. MIT License.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsintef%2Ffortran-stacktrace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsintef%2Ffortran-stacktrace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsintef%2Ffortran-stacktrace/lists"}