hare-module.5.scd (3538B)
1 hare-module(5) 2 3 # NAME 4 5 hare-module - Hare module layout 6 7 # DESCRIPTION 8 9 Hare modules are represented as directories in the filesystem. A directory is a 10 valid Hare module if it contains at least one Hare source file (with the file 11 extension *.ha*), or if it contains a file named *README*. 12 13 All files which end in *.ha*, *.s*, and *.o* are treated as inputs to the 14 module, and are respectively treated as Hare sources, assembly sources, and 15 objects to be linked into the final binary. 16 17 The list of files considered eligible may be filtered by build tags (see *BUILD 18 TAGS* below). The format for the filename is _name_[_tagset_]._ext_, where the 19 _name_ is user-defined, the _ext_ is either *ha*, *s*, or *o*, and a tagset (see 20 *BUILD TAGS*) is optionally provided after the name. A file will only be 21 included if all tags included (with +) in the tagset are present, and no tags 22 excluded (with -) in the tagset are present. 23 24 Only one file for a given combination of _name_ and _ext_ will be selected for 25 the build; the file selected is the one with the most tag specifiers. If there 26 are two or more such files, the build driver will error out. 27 28 For example, if the following files are present in a directory: 29 30 - foo.ha 31 - bar.ha 32 - bar+linux.ha 33 - bar+plan9.ha 34 - baz+x86_64.s 35 - bat-x86_64.ha 36 37 If the build tags are +linux+x86_64, then the files which are included in the 38 module are foo.ha, bar+linux.ha, and baz+x86_64.s. If the following files are 39 added: 40 41 - meep+linux-libc.ha 42 - meep+linux+x86_64.ha 43 44 then the build driver will error out, unless +libc is added to the build tags. 45 46 Additionally, subdirectories in a module will be considered part of that module 47 if their name consists only of a tagset, e.g. "+linux" or "-x86_64". A directory 48 with only a name (but without a tagset, e.g. "example") is considered a 49 submodule, and as such must be imported separately. For example, "foo::bar" 50 refers to foo/bar/. If a directory name contains both a name and a tagset, the 51 build driver will error out. 52 53 # DEPENDENCY RESOLUTION 54 55 The "use" directives in each Hare source file used as an input to 56 *hare-build*(1), *hare-run*(1), or *hare-test*(1) are scanned and used to 57 determine the dependencies for a program. This process is repeated for each 58 dependency to obtain a complete dependency tree. 59 60 Dependencies are searched for by examining first the current working directory, 61 then each component of the *HAREPATH*, which is a list of paths separated by 62 colons. *HAREPATH* is obtained from the environment variable of the same name. 63 If the environment variable is unset, a default value is used, which can be 64 viewed with the *hare version -v* command. Typically, it is set to include the 65 path to the standard library installed on the system, as well as a 66 system-provided location for third-party modules installed via the system 67 package manager. 68 69 *hare-deps*(1) may be used to print the dependency tree of a Hare module. 70 71 # BUILD TAGS 72 73 Build tags allow you to add constraints on what features or platforms are 74 enabled for your build. A tag is a name, consisting of characters which aren't 75 any of '+', '-', or '.', and a '+' or '-' prefix to signal inclusivity or 76 exclusivity. 77 78 To add or remove build tags, use the *-T* flag. For example, *-T +foo-bar* will 79 add the 'foo' tag and remove the 'bar' tag. 80 81 Some tags are enabled by default, enabling features for the host platform. You 82 can view the default tagset by running *hare version -v*. To remove all default 83 tags, use *-T^*. 84 85 # SEE ALSO 86 87 *hare*(1), *hare-build*(1), *hare-run*(1), *hare-test*(1)