Project structure
=================

You may organize your Hare projects to whatever extent you find preferable or
necessary to support your use-case. However, we do have conventions on how most
Hare projects are structured which you may find useful as a consistent
baseline.

Directory structure
-------------------

Hare users are encouraged to place directories containing Hare modules directly
at the root of their project, such that files comprising the "example" module
would appear at ``example/*.ha``. Additionally, a few other directories have a
prescribed conventional usage:

* ``cmd/*/``: executable programs (e.g. ``cmd/example/*.ha``)
* ``doc/``: manual pages or other documentation separate from haredocs
* ``scripts/``: shell scripts, if applicable
* ``internal/``: modules relevant to ``cmd/*/`` but not installed [#install]_

The files ``COPYING``, ``README.md`` or ``README``, and ``Makefile`` often
appear at the root of the project tree, corresponding to their broadly
conventional usage. The ``Makefile`` is explained in the next section.

If you have no particular opinions or needs with respect to software licensing,
Hare projects tend to prefer `MPL 2.0
<https://www.mozilla.org/en-US/MPL/2.0/>`_ for libraries and `GPLv3
<https://www.gnu.org/licenses/gpl-3.0.en.html>`_ for executables.

.. rubric:: Footnotes

.. [#install] An ``internal/`` directory is only necessary if you have a
   project which provides both executables and installable modules.

Makefiles
---------

Hare projects usually include a Makefile to facilitate building and installing
the project. These Makefiles should provide the following (.PHONY) targets as
applicable:

* **all**: build all executables. This should be the default (first) target.
* **check**: run tests (``hare test``)
* **clean**: remove build artifacts
* **docs**: build documentation (e.g. man pages)
* **install-bin**: install executables
* **install-docs**: install documentation
* **install-lib**: install Hare modules
* **install**: install everything
* **uninstall-bin**: uninstall executables
* **uninstall-docs**: uninstall documentation
* **uninstall-lib**: uninstall Hare modules
* **uninstall**: uninstall everything

Hare projects should install to the ``/usr/local`` PREFIX by default, and
respect the PREFIX and DESTDIR variables.

Two example Makefiles are provided here to get you started; feel free to merge
or expand these to suit your project's specific needs.

Example Makefile with executables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is an example Makefile for a project which only installs executables:

.. include:: exe.Makefile
   :code: Makefile
   :tab-width: -1

Example Makefile with modules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is an example project which only installs Hare modules, "example1" and
"example2":

.. include:: lib.Makefile
   :code: Makefile
   :tab-width: -1