We are happy to merge your pull requests!
The IHP framework itself uses devenv.sh to set up the development environment. It is a wrapper around nix develop
and direnv
.
Follow the devenv documentation to set it up.
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 devenv up
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
devenv up
Running devenv up
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. You can keep devenv up
running, as it will pick up any changes to the custom app or the IHP, and save you the hassle of manually recompiling from ghci on every change.
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
# Enable direnv
cd IHP
direnv allow
# Go back to the project root (do not run inside the IHP directory)
cd -
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.
We need to make sure not to commit the changes of IHP/ihp.nix
To help us with that, you can run this from the root of your project cd IHP && git update-index --assume-unchanged ihp.nix
, so git will ignore your changes.
If you're testing local nix changes, you need to change your flake.nix
to point to the IHP project instead of pulling it from github:
{
inputs = {
# The path needs to be absolute
ihp.url = "path:///Users/myuser/someproject/IHP";
# ...
};
After that run nix flake update
.
When contributing to IHP core you will want to have your PRs synced with master
. Your flake.nix
should have this line:
{
ihp.url = "github:digitallyinduced/ihp";
}
Then every time you'd like to update to the latest master, you'll run:
nix flake update
direnv allow
Note that it takes around 30 minutes for the IHP GitHub actions to prepare a binary build of IHP. If you run latest master and the GitHub actions aren't finished yet, you will notice that your computer needs to build IHP from scratch which takes a lot of time. You can wait for the GitHub action to complete or point to a specific IHP commit to avoid long build times.
When making changes to the development tooling, we have to start the server differently, without devenv up
. We have to
use make console
to load your application together with the framework located in IHP
.
ghci
:l IHP/exe/IHP/IDE/DevServer.hs
main
We don't need to start postgres as the IDE starts it automatically.
You can enable additional 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, switch to the IHP
directory. When you're doing this the first time, you need to run direnv allow
to install necessary dependencies:
cd IHP
direnv allow
Then switch to the Guide
directory and run direnv allow
again:
cd Guide
direnv allow
To rebuild the html files from the markdown files on every file change run:
devenv up
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
.return
might 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:
ghci
:l Test/Main.hs
main
Note that if it's the first time you switch to the IHP
directory, you need to run direnv allow
. This will then download all dependencies needed for IHP development automatically.
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
.
Since the switch to nix flakes with IHP v1.1 we're using release branches, to make it easy to upgrade IHP versions using nix flake update
.
E.g. there's a branch named v1.1
that contains the latest IHP v1.1.x release. When a new IHP v1.1.x release is made, we'll update the v1.1
branch to point to the new release commit.
IHP apps have a flake.nix
like this:
{
inputs.ihp.url = "github:digitallyinduced/ihp/v1.1";
}
This means that whenever someone runs nix flake update
, they'll get the latest commit from the IHP v1.1 branch.
This will also lead to a change of the flake.lock
file in the project. This file ensures that IHP is consistently reproduced across machines, so users should also make sure to check this change into git.
To upgrade to a newer minor version, the URL can be changed to use IHP from the e.g. v1.2
branch:
{
inputs.ihp.url = "github:digitallyinduced/ihp/v1.2";
}
In the same way as with updating, running nix flake update
after declaring a new version will update the flake.lock
file to ensure consistency in all environments.
When we're preparing a new release, e.g. the IHP v1.2.0 release, we'll create a new branch v1.2
and merge the current master into that branch.
Additionally every released version of IHP is tagged. You can see a list of all tags on GitHub.
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.
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)
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
devenv up
Practical resources to get you up to speed with tools IHP uses.