We are happy to merge your pull requests!
To work on the framework in your application, you need to clone this repository inside your application directory.
If you don't have a project, first make sure you have the latest version of ihp-new, update it by running: nix-env -f https://downloads.digitallyinduced.com/ihp-new.tar.gz -i ihp-new. Use ihp-new to create one. Make sure to run ./start in your project once. Also make sure that direnv is set up in your shell.
# Set up a local IHP project
ihp-new myproject
cd myproject
./start
Running ./start is necessary, even if you don't intend to run it this way (e.g. you intend to do development and don't intend to run it "normally"), to do some initial setup like creating the database. When it starts normally, just CTRL+C to exit.
Clone the IHP repository into the project directory. The IHP directory is added to the GHC search path in applicationGhciConfig. Therefore when the IHP directory exists, GHC will load all IHP modules from there.
git clone [email protected]:digitallyinduced/ihp.git IHP
# only needs to be run once (do not run inside the IHP directory)
make -B build/ihp-lib
Uncomment the configureFlags = [ "--flag FastBuild" ]; and doHaddock = false; lines in the IHP/ihp.nix for fast rebuilds, otherwise you could up waiting up to half an hour while IHP builds itself.
The best workflow is to use make console to load your application together with the framework located in IHP. In a nix-shell:
ghci
$ghci> :l Main
This will now load your application and all the haskell files in IHP.
As we are not using the development tooling for the framework development process we need to manually start the postgres process by running postgres -D build/db/state -k $PWD/build/db -c "listen_addresses=" in another terminal window.
After postgres is started you can now start the application with the local framework version by running:
main
After you have made modifications to files inside IHP, you need to press CTRL + C to stop the process running in ghci and then type :r to refresh the haskell modules. Now type main to start the server again.
When making changes to the development tooling, follow the setup above, except don't start postgres (the IDE starts it automatically).
Instead of starting your application, start the development server:
ghci
:l IHP/exe/IHP/IDE/DevServer.hs
main
You can enable additonal debug logging for the development server by setting the env variable DEBUG=1. Like this:
export DEBUG=1
ghci
:l IHP/exe/IHP/IDE/DevServer.hs
main
To work on the documentation locally open a nix shell inside the framework directory:
cd IHP
nix-shell
Then switch to the Guide directory:
cd Guide
To rebuild the html files from the markdown files on every file change run:
make watch
This will automatically open a browser window with the compiled html of the documentation. You can now make changes to the markdown files and they are reflected in the browser after a page refresh.
When adding a new markdown page also add it to the Makefile. Otherwise it will not be built.
The documentation reads a bit like a tutorial, but should still be kept somewhat complete. Still, refer the reader to the API docs for comprehensive explanations, technical details or less-used functionality. After all, the target audience is coders.
-
Please use
pure.returnmight confuse people coming from other programming languages. -
Please add Haddock-comments to new methods intended to be used by directly when developing using IHP.
-
Please consider carefully before adding new packages as requirements to IHP itself. Make sure the packages are actively maintained.
When inside the IHP directory, you can run the Test Suite by loading it into a ghci like this:
nix-shell
ghci
:l Test/Main.hs
mainNote that it is necessary to start the nix-shell from within the IHP directory to pick up an extra package used in testing.
When doing changes to the test files, use this to reload and rerun the tests:
:r
main
After creating a new test you need to still call it from the Main module by adding it to IHP/Test/Main.hs.
If you get an error like can't satisfy package ihp or all other IHP packages when running ghci most likely the symlink in build/ihp-lib is not set up as expected. IHP uses the symlink build/ihp-lib in your application's .ghci file to access IHP/lib/IHP/applicationGhciConfig. This applicationGhciConfig sets up all the required options for ghci.
Try to run make -B build/ihp-lib to create the symlink.
In the project directory, try make -B .envrc
You may receive this error when trying to load modules into GHCI like :l Main. Run chmod go-w . to change the permissions so the .ghci file could be loaded properly.
Perhaps a package was added to IHP recently. Start a nix-shell in the IHP directory to fetch missing packages.
Either add the package to your project's default.nix as well, or change the section ihp = builtins.fetchGit ... to ihp = ./IHP;in your project's default.nix. Then the IHP/ihp.nix will be used to fetch packages.
The errors comes from changes to the Schema Compiler, so build/Generated/Types.hs is outdated. The error only happens when we have backwards compatibility breaks in some of the interfaces, which doesn't happen very often. If you do get them you should execute from your appication's root directory (not the IHP directory)
nix-shell
ghci
:l IHP/IHP/SchemaCompiler.hs
compile
After this the error should be gone, and you can go back to :l Main
If you want to go back and use the standard IHP library instead of the cloned source, for instance when your much needed, contributed and approved feature becomes part of the release, then in your project directory:
rm -rf IHP
rm build/ihp-lib
./start
Practical resources to get you up to speed with tools IHP uses.