hare-build.1.scd (4622B)
1 hare-build(1) 2 3 # NAME 4 5 hare build - compile a Hare program or module 6 7 # SYNOPSIS 8 9 *hare build* [-hFqv]++ 10 [-a _arch_]++ 11 [-D _ident[:type]=value_]++ 12 [-j _jobs_]++ 13 [-L _libdir_]++ 14 [-l _libname_]++ 15 [-N _namespace_]++ 16 [-o _path_]++ 17 [-R]++ 18 [-T _tagset_]++ 19 [-t _type_]++ 20 [_path_] 21 22 # DESCRIPTION 23 24 ; TODO: Decide on and document driver exit statuses 25 *hare build* compiles a Hare program or module. The _path_ argument is a path to 26 a Hare source file or to a directory which contains a Hare module (see 27 *hare-module*(5)). If no path is given, the Hare module contained in the current 28 working directory is built. 29 30 # OPTIONS 31 32 *-h* 33 Print the help text. 34 35 *-F* 36 Build for freestanding (non-hosted) environment. See *FREESTANDING 37 ENVIRONMENT*. 38 39 *-q* 40 Outside of errors, don't write anything to stdout while building. 41 42 *-v* 43 Enable verbose logging. Specify twice to increase verbosity. 44 45 *-a* _arch_ 46 Set the desired architecture for cross-compiling. See *ARCHITECTURES* 47 for supported architecture names. 48 49 *-D* _ident[:type]=value_ 50 Define a constant in the type system. _ident_ is parsed as a Hare 51 identifier (e.g. "foo::bar::baz"), _type_ as a Hare type (e.g. "str" or 52 "struct { x: int, y: int }"), and _value_ as a Hare expression (e.g. 53 "42"). Take care to address any necessary escaping to avoid conflicts 54 between your shell syntax and Hare syntax. 55 56 *-j* _jobs_ 57 Set the maximum number of jobs to execute in parallel. The default is 58 the number of processors available on the host. 59 60 *-L* _libdir_ 61 Add a directory to the linker library search path. 62 63 *-l* _libname_ 64 Link with the named system library. The name is passed directly to the 65 linker. Linking with any library will also link with *libc*(7) and add 66 the +libc tag to the default build tags (see *BUILD TAGS* in 67 *hare-module*(5)). 68 69 *-N* _namespace_ 70 Override the namespace for the module. 71 72 *-o* _path_ 73 Set the output file to the given path. Setting the path to *-* causes 74 output to be written to stdout. 75 76 *-R* 77 Build in release mode. In debug mode (the default), the debug:: module 78 is imported as a dependency, which automatically installs a number of 79 runtime debugging features in your executable. See this module's 80 documentation for details on these features. 81 82 *-T* _tagset_ 83 Set or unset build tags. See *BUILD TAGS* in *hare-module*(5). 84 85 *-t* _type_ 86 Set the build type. _type_ should be one of s, o, or bin, for assembly, 87 compiled object, or compiled binary, respectively. The default build 88 type is compiled binary. 89 90 # ARCHITECTURES 91 92 The *-a* flag is used for cross-compilation to a target architecture different 93 from the host architecture. The following architectures are currently supported: 94 95 - aarch64 96 - riscv64 97 - x86_64 98 99 The system usually provides reasonable defaults for the *AR*, *AS*, *LD*, and 100 *CC* tools based on the desired target. However, you may wish to set these 101 variables yourself to control the cross toolchain in use. 102 103 # FREESTANDING ENVIRONMENT 104 105 If run with *-F*, hare build will target a freestanding environment. This has 106 the following effects: 107 108 - No constraints are imposed on the signature of "main" 109 - Specifying external libraries with *-l* will *not* automatically: 110 - Link with libc (add *-lc* manually if required) 111 - Add the +libc flag (add *-T+libc* manually if required) 112 - Use the C compiler for linking (use *LD=cc* if required) 113 114 # ENVIRONMENT 115 116 The following environment variables affect *hare build*'s execution: 117 118 |[ *HARECACHE* 119 :< The path to the build cache. Defaults to *$XDG_CACHE_HOME/hare*, or 120 *~/.cache/hare* if *$XDG_CACHE_HOME* isn't set. 121 | *HAREPATH* 122 : The list of directories to search for module dependencies in. See 123 *hare-module*(5). 124 | *NO_COLOR* 125 : Disables all color output when set to a non-empty string. 126 | *HAREC_COLOR* 127 : Disables color output for *harec* when set to 0, enables it when set to any 128 other value. This overrides *NO_COLOR*. 129 | *HAREC* 130 : Name of the *harec* command to use. 131 | *HARECFLAGS* 132 : Additional flags to pass to *harec*. 133 | *QBE* 134 : Name of the *qbe* command to use. 135 | *QBEFLAGS* 136 : Additional flags to pass to *qbe*. 137 | *AR* 138 : Name of the *ar*(1) command to use. 139 | *ARFLAGS* 140 : Additional flags to pass to *ar*(1). 141 | *AS* 142 : Name of the *as*(1) command to use. 143 | *ASFLAGS* 144 : Additional flags to pass to *as*(1). 145 | *LD* 146 : Name of the *ld*(1) command to use. 147 | *LDLINKFLAGS* 148 : Additional flags to pass to *ld*(1). 149 | *CC* 150 : Name of the *cc*(1) command to use when linking external libraries. 151 | *LDFLAGS* 152 : Additional linker flags to pass to *cc*(1). 153 154 # SEE ALSO 155 156 *hare-run*(1), *hare-test*(1), *hare-module*(5), *ar*(1), *as*(1), *cc*(1), 157 *ld*(1)