~khumba/hoppy

C++ FFI generator for Haskell

#52 handleExceptions docs are incorrect, handlers are prepended

~khumba commented on hoppy todo

19 days ago

#52 handleExceptions docs are incorrect, handlers are prepended

~khumba commented on hoppy todo

19 days ago

#Hoppy - A C++ FFI generator for Haskell

Hoppy brings all the fun of pointers and manual memory management to Haskell, making binding to C++ easy.

Homepage: https://khumba.net/projects/hoppy

Sourcehut project: https://sr.ht/~khumba/hoppy/

User's Guide: https://hackage.haskell.org/package/hoppy-docs/docs/Foreign-Hoppy-Documentation-UsersGuide.html

Copyright 2015-2024 Bryan Gardiner bog@khumba.net

A range of successive copyright years may be written as XXXX-YYYY as an abbreviation for listing all of the years from XXXX to YYYY inclusive, individually.

The LICENSE file contains information about Hoppy's license. Hoppy uses two licenses, for different parts of the project.

#Moved to Sourcehut

As of May 2024, Hoppy development has moved from Gitlab to Sourcehut. Further development will continue here:

https://sr.ht/~khumba/hoppy/

The Gitlab project will be archived and may be removed at some point in the future:

https://gitlab.com/khumba/hoppy

#Using

Hoppy requires GHC 8.2 or newer.

If you just want to install Hoppy to use it as a dependency of another project, then all you need to do is build and install the Cabal package in runtime/.

Hoppy consists of four Cabal packages:

  • generator/ holds the code generator library. Developers specify interfaces in Haskell code, that then link against this library to produce a generator program that can create actual binding source code. This package is only used while generating code, and isn't a dependency of generated bindings.

  • std/ provides interface definitions for the C++ standard library, including strings, containers, and iterators.

  • runtime/ is a runtime support library for Haskell bindings. This is needed by generated Haskell code, so bindings created using Hoppy should list this as package as a dependency in their .cabal files.

  • docs/ contains documentation written using Haddock. It depends on the previous packages for hyperlinks.

Hoppy is easiest to build with the Cabal v2-style commands. See cabal.project for a list of main packages, tests, and examples that can be built, or build everything with the following command. Note that directory names do not match package names, so refer to the .cabal files to see what package names can be given to Cabal:

cabal v2-test all && cabal v2-build all

An old Cabal v1-style build can be done with the install.sh script, but no tests or examples are built.

If you are using the Nix package manager, see README.nix.md for more information about using Hoppy with it.

There is a user's guide written using Haddock at docs/src/Foreign/Hoppy/Documentation/UsersGuide.hs. You can read it as is, or browse the HTML files in docs/dist/doc after building, or read it prerendered on Hackage at the link at the top of this file.

#Developing

Patches are welcome! Please enable the pre-commit hook at scripts/git-pre-commit which checks lint and copyright/license issues:

$ ln -s ../../scripts/git-pre-commit .git/hooks/pre-commit

Also please try to fix warnings that your changes introduce, check that the unit tests in the tests/ directory pass, and follow local style, or the style guide.