INSTALL.md (10206B)
1 # Installing Unison 2 3 ## Pre-built binaries 4 5 The easiest and quickest way is to install pre-built binaries available at many 6 package repositories. The caveat: some repositories are slow to update and 7 often include a very old version of Unison. 8 9 Alternatively, some pre-built binaries are made available at 10 https://github.com/bcpierce00/unison/releases for macOS, Linux and Windows. 11 No specific installation is needed, just unpack the files at a location of your 12 choosing. 13 14 ## Building from source 15 16 ### Packaging systems 17 18 Many packaging systems, including source-based systems like `pkgsrc` 19 and binary repositories like Debian GNU/Linux, make it easy to build 20 from source by handling all the dependencies for you and encoding the 21 unison build recipe. Please refer to instructions provided by the 22 packaging system. (Issues about packaging systems should be filed 23 with those systems, and not in the unison issue tracker.) 24 25 ### Mostly-POSIX systems (GNU/Linux, BSDs, macOS, illumos-based OS, Solaris) and Cygwin 26 27 #### Build prerequisites 28 29 - A C99 compiler (e.g. gcc, clang) 30 - A recent version of OCaml compiler (version 4.08 at minimum) 31 -- see https://ocaml.org/. (Note that ocaml upstream says that 5.x is 32 experimental. The standard approach is the most recent 4.x ocaml 33 release.) 34 - make (any of GNU, BSD, Solaris variants works) 35 - Basic POSIX tools (e.g., echo, install, rm, sh, sed, touch) 36 37 ##### Optional, for the GUI only 38 39 - lablgtk3 and its prerequisites (GTK 3 and its dependencies) 40 - ocamlfind (there is backup code to operate without it in some circumstances) 41 42 ##### Optional, on BSDs, for building unison-fsmonitor 43 44 - pkg-config 45 - libinotify 46 47 ##### Optional, for building the user manual 48 49 - sed 50 - LaTeX 51 - pdf2ps (optional, for PS output; included with Ghostscript, for example) 52 - HEVEA (https://hevea.inria.fr/) (optional, for HTML and text formats) 53 - Lynx (optional, for text format) 54 - (for developers only) HEVEA and Lynx are required to re-build the manual 55 included in the Unison binary 56 57 #### Building 58 59 To build from source, first ensure that all prerequisites are 60 installed. See each prerequisite's documentation for instructions, or 61 use a package manager. 62 63 Building from source is as simple as changing to the source directory 64 and executing: 65 ``` 66 make 67 ``` 68 If you are using OPAM then `opam exec -- make` may work for you, as opam needs 69 to set up a specific environment. 70 71 Presence of lablgtk3 is detected automatically to build the GUI. On 72 BSDs, the presence of libinotify is detected automatically. On 73 systems supported by one of the unison-fsmonitor variants, it is built 74 automatically. 75 76 If you want to build only the GUI, type `make gui`. You can type `make 77 tui` if you have lablgtk3 installed but don't want the GUI built. Type 78 `make fsmonitor` to build only the filesystem monitor. 79 80 To install: 81 - set `$PREFIX` in the environment if you don't want /usr/local 82 - optionally set `$DESTDIR` 83 - run `make install`. 84 85 The set of installed files (paths from the source directory) should be 86 ``` 87 src/unison (the main executable for TUI/CLI) 88 src/unison-gui (the main executable for GUI) 89 src/unison-fsmonitor (optional, on some build platforms) 90 man/unison.1 (optional, manual page) 91 doc/unison-manual.* (optional, user manual in different formats) 92 ``` 93 94 ### Cross-compiling for a different target architecture or OS 95 96 To cross-compile for a different target, you need to have a cross-compilation 97 toolchain including both a cross-compiling C compiler and a cross-compiling 98 OCaml compiler. When you have cross-compilation toolchain in place, building 99 Unison from source works according to instructions above. You just have to add 100 a `TOOL_PREFIX` argument to `make` to indicate which toolchain to use (and 101 ensure the tools are in `$PATH`). 102 103 For example, to build a native Windows 64-bit executable using the MinGW 104 cross-compilation toolchain: 105 ``` 106 make TOOL_PREFIX=x86_64-w64-mingw32- 107 ``` 108 109 Building the manual page and documentation does not work when cross-compiling. 110 To build the documentation, first build Unison without cross-compilation. 111 112 113 ### macOS 114 115 First, note that macOS is a mostly-POSIX system and see that section 116 above. 117 118 Second, note that macOS by default is missing a number of expected 119 tools, including POSIX-required system headers (e.g. all of 120 /usr/include). The standard approach on macOS is to install either 121 Command Line Tools or Xcode, so that one has a working 122 C99/mostly-POSIX environment. These also allow building against the 123 libraries required for the mac-native GUI. 124 125 There is no support in the unison sources for unison-fsmonitor on 126 macOS. See 127 https://github.com/bcpierce00/unison/wiki/Software-for-use-with-Unison 128 for a list of fsmonitor implementations maintained outside the unison 129 source tree. 130 131 #### Building 132 133 The mostly-POSIX instructions above will build the text user 134 interface, the GTK GUI and, if you have native GUI headers/libs, also 135 the macOS native GUI. 136 137 To build only the macOS native GUI, execute: 138 ``` 139 make macui 140 ``` 141 142 The built application will be located at `src/uimac/build/Default/Unison.app`. 143 144 ### Windows 145 146 Builds are possible with MS Visual C++ (MSVC) and MinGW-w64 compilers. 147 148 To build Unison for usage within Cygwin environment (not a native Windows 149 executable), follow build instructions for Unix-like OS above. 150 151 The build system automatically detects if the build is of MSVC, MinGW or Cygwin 152 GNU C (not native Windows) type based on the first OCaml compiler (ocamlc and 153 ocamlopt) found on PATH. Thus, if you have multiple compilers, you can easily 154 select between these methods by adjusting the PATH accordingly when running 155 `make`. 156 157 #### MinGW 158 159 Building with MinGW, you need a Cygwin installation as the POSIX-like build 160 environment (if you are using OPAM, this can be installed automatically by 161 OPAM). Cygwin is not required to run the produced executables. You need to 162 have the following prerequisites: 163 164 - MinGW gcc and MinGW binutils (Cygwin package example mingw64-x86_64-gcc-core) 165 - A recent version of OCaml compiler (version 4.08 at minimum) which itself is 166 built with MinGW gcc (it is possible to find pre-compiled binaries); do not 167 use the Cygwin OCaml package as that is not compiled with MinGW. If using 168 OPAM, be sure to include the system-mingw OPAM package when installing the 169 OCaml compiler. 170 - GNU make 171 - A POSIX shell (available in Cygwin by default) 172 173 To build, change to directory where Unison source code is and execute: 174 ``` 175 make 176 ``` 177 178 If all goes well, the following files will be produced: 179 ``` 180 src/unison.exe (the main executable for TUI/CLI) 181 src/unison-gui.exe (the main executable for GUI, optional, see below) 182 src/unison-fsmonitor.exe (filesystem monitor, optional) 183 ``` 184 185 You can check which DLLs are needed by the built binary by executing 186 `cygcheck src/unison.exe` or `ldd src/unison.exe`. 187 188 For building the GUI (optional), you also need the following: 189 190 - MinGW GTK 3 and its dependencies (Cygwin package example mingw64-x86_64-gtk3) 191 - Some MinGW GTK icon theme (optional, but recommended; Cygwin package example 192 mingw64-x86_64-adwaita-icon-theme) 193 - lablgtk3 and its prerequisites (ocamlfind, dune build system) 194 195 Building lablgtk3 from source is complicated. It is recommended to use OPAM for 196 that (Cygwin package name opam). Make sure that OPAM uses the MinGW version of 197 gcc and binutils. 198 199 #### MSVC 200 201 When building with MSVC, a Cygwin installation is not needed. It is possible to 202 find pre-compiled OCaml compiler binaries, but it may be easiest to use OPAM as 203 it will also automatically set up the correct environment for using MSVC and 204 NMAKE. You need to have the following prerequisites: 205 206 - Microsoft Visual C++ (MSVC). A complete Visual Studio installation is not 207 required, having Build Tools installed is sufficient. The build tools, 208 including NMAKE, must be found in PATH. 209 - A recent version of OCaml compiler (version 4.08 at minimum) which itself 210 is built with MSVC. If using OPAM, be sure to include the system-msvc OPAM 211 package when installing the OCaml compiler. 212 213 To build, change to directory where Unison source code is and execute: 214 ``` 215 nmake 216 ``` 217 218 If all goes well, the following files will be produced: 219 ``` 220 src\unison.exe (the main executable for TUI/CLI) 221 src\unison-gui.exe (the main executable for GUI, optional, see below) 222 src\unison-fsmonitor.exe (filesystem monitor, optional) 223 ``` 224 225 For building the GUI (optional) with MSVC, you also need the following: 226 227 - A native Windows GTK 3 installation (try https://github.com/wingtk/gvsbuild). 228 Do not use GTK for Cygwin or MinGW. 229 Make sure the installation location (typically C:\gtk\bin) is in the PATH 230 environment variable. If building lablgtk3/cairo2 fails with errors related 231 to pkgconf or pkg-config then you may also need to set the PKG_CONFIG_PATH 232 environment to point to C:\gtk\lib\pkgconfig (adjust according to your GTK 233 installation location). 234 - lablgtk3 and its prerequisites (ocamlfind, dune build system) 235 236 Once built, a GTK 3 installation must be found in PATH or DLLs for GTK 3 be 237 present where unison-gui.exe is located in order to run the GUI. 238 239 ### Build options 240 241 There are some additional options that control the build process: 242 243 - NATIVE: If you can't compile a native binary for your platform then add 244 `NATIVE=false` as argument to `make`. This will produce a single native 245 executable with OCaml runtime and Unison bytecode embedded. 246 - CFLAGS, CPPFLAGS, LDFLAGS, LDLIBS control the build process as usual. 247 OCaml compiler will pass these arguments on to the C compiler and linker. 248 - To produce a statically linked executable, add arguments suitable for your 249 platform and toolchain in your LDFLAGS. Static linking mostly makes no 250 difference because some widely-used C libraries, like glibc, do not allow 251 static linking, GTK does not allow static linking and there is nothing to 252 link statically for the textual user interface in Windows and Cygwin. 253 Examples of LDFLAGS values to enable static linking: 254 `-static` or `-Wl,-static` for gcc (should also work for clang); 255 `-link -static` for gcc in Windows (MinGW, Cygwin, MSYS2) ("-link" is 256 required due to flexlink being used in the toolchain).