// -*- mode:doc; -*-
// vim: set syntax=asciidoc:

=== Infrastructure for Hare packages

[[hare-package-tutorial]]

==== +hare-package+ tutorial

The +Config.in+ file of Hare-based package 'hare-foo' should contain:

----
01: config BR2_PACKAGE_HARE_FOO
02: 	bool "hare-foo"
03: 	depends on BR2_PACKAGE_HOST_HARE_TARGET_ARCH_SUPPORTS
04: 	select BR2_PACKAGE_HOST_HARE
05: 	help
06: 	  This is a comment that explains what foo is.
07:
08: 	  https://foosoftware.org/foo/
----

And the +.mk+ file for this package should contain:

----
01: ################################################################################
02: #
03: # hare-foo
04: #
05: ################################################################################
06:
07: HARE_FOO_VERSION = 0.42.0
08: HARE_FOO_SITE = https://git.sr.ht/~sircmpwn/hare-foo
09: HARE_FOO_SITE_METHOD = git
10: HARE_FOO_LICENSE = MPL-2.0
11: HARE_FOO_LICENSE_FILES = COPYING
12: HARE_FOO_INSTALL_STAGING = YES
13:
14: $(eval $(hare-package))
----

The Makefile starts with the definition of the standard variables for
package declaration (lines 7 to 12).

Finally, on line 14, we invoke the +hare-package+
macro that generates all the Makefile rules that actually allows the
package to be built.

[[hare-package-reference]]

==== +hare-package+ reference

As a policy, packages that provide Hare modules should all be
named +hare-<something>+ in Buildroot.

In their +Config.in+ file, packages using the +hare-package+
infrastructure should depend on +BR2_PACKAGE_HOST_HARE_TARGET_ARCH_SUPPORTS+
because Buildroot will automatically add a dependency on +host-hare+
to such packages.

The main macro of the Hare package infrastructure is +hare-package+:
like +generic-package+ it works by defining a number of variables providing
metadata information about the package, and then calling the +hare-package+
macro.

Just like the generic infrastructure, the Hare infrastructure works
by defining a number of variables before calling the +hare-package+
macro.

All the package metadata information variables that exist in the
xref:generic-package-reference[generic package infrastructure] also
exist in the Hare infrastructure.

This infrastructure expects that the upstream package follows the
https://harelang.org/documentation/usage/project-structure.html#makefiles[project structure conventions],
because the upstream +Makefile+ is called.

When the package contains Hare modules (ie. libraries),
there are not compiled by this BR package,
there are just installed in +$(STAGING_DIR)/usr/src/hare/third-party+,
for a future use.

When the package produces one or more executables,
all Hare sources (from this package, from dependent modules,
from the Hare stdlib) are compiled and statically linked.
If a binding to a native library is used,
the link requires the static library, not the shared one.
