Creating new packages

Creating a new empty package

If you're starting from scratch and don't have any code written for the package, following these steps should get you there:

1. Create a directory for your package and cd into it.

2. Run cabal init and answer the questions.
   Most of the questions are self-explanatory, but it's good to keep in mind that

   • Project synopsis is a short description about the package,
   • answering y to the Include documentation of each field? question really helps make the cabal file more readable.
   • Source directory: If you want to use the project root as your source directory, choose option 3 (other) and then specify . as the answer. However, it's good practice and usually best to keep the source files under the src directory (unless this package is a sub-package).

3. Congratulations! You're done.

You can try creating a sandbox, installing the dependencies and building:

cabal sandbox init
cabal install --only-dependencies
cabal build

Creating a new package for existing code

1. Before creating the package, you should move the code to its new location and where you want it to be. This step is synonymous with step 1. of the 'new empty package' guide above.
   E.g. In commit f6697c5, I moved the files from src/Latex/ into latex/Latex/, where latex will be a new package.

2. Run cabal init (same tips as above apply).

3. Look at the cabal file of the package where the code previously resided, and copy/move over the package dependencies listed in the build-depends field.

4. Currently, by default cabal creates a field called other-extensions in the cabal file for the new package. You probably want to change that to default-extensions to tell GHC to use the extensions for all files in the package. See here for more info.

5. Remove the list of modules of the package from its the cabal file of its previous package, and be sure to add the name of your new package to build-depends of the other cabal file.

6. If the project uses Stack, modify stack.yaml to include the new package.
   E.g. add latex/ to the packages: section in the stack file.

7. Literate Unit-B currently has a custom build script integrated into Sublime Text's build system (Cmd-B). Be sure to add the new package directory to the search path in script/Build.hs (see 874aa64), and also to the literate-unitb.sublime-project file too.

Now you can proceed to tell cabal to use the sandbox of the parent project for this package, add the new package to list of sources, install dependencies (to build the new package) and build the parent project:

cabal sandbox init --sandbox=..
cd ..
cabal sandbox add-source latex/
cabal install --only-dependencies
cabal clean
cabal build