2 .\" Copyright (c) 2009-2011, Charles McGarvey
3 .\" All rights reserved.
5 .\" Distributable under the terms and conditions of the 2-clause BSD
6 .\" license; see the file COPYING for a complete text of the license.
13 .Nd building and installation instructions for yoink
15 Yoink can usually be built and installed in the same way as most other open
16 source packages, using the following commands:
20 .D1 make && make install
22 Yet, although the build system scripts and makefiles follow standard
23 conventions, they are themselves a little unconventional. Therefore, if
24 things go wrong, this reference may aid in diagnosing the problem. The
25 rest of this page is for those for whom the basic steps do not work or for
26 those who have specialized needs, like packagers.
30 script is provided in the package to help prepare the build system to
31 compile and install Yoink on your particular system. This script supports
32 many of the same options as your typical Autoconf-generated script. Just
35 flag to see which options are available.
37 In particular, you may use the
39 flag to set where Yoink will be installed. The default directory prefix is
41 which is a good idea in most cases, as long as you have write permissions
42 for that directory. Otherwise, you might want to set the prefix to be some
43 directory within your home directory.
45 The script also supports the
47 flag to allow for cross-compiling. Use this flag to set the triplet of the
48 machine architecture and system software combination for the platform you
49 want Yoink to run on. Of course, you will need the appropriate toolchain
54 installed, an alternative approach to configuration is to use
56 the interactive menu system built into the
58 script. To use this method, there exists a familiar
60 target to bring up the menu dialogs:
64 This is the same as running the
68 flag. This allows you to browse the various options and make changes to
69 the configuration before it is saved in preparation for building.
71 Regardless of which way
73 is run, it will perform various checks and make sure the required
74 dependencies are found. If all of the checks pass, the configuration file
77 and the script will terminate with an exit code of 0. If any checks fail,
78 a non-zero exit code will result. The configuration file,
80 can be edited manually if desired. However, the
82 script should be run again afterward to make sure the changes didn't cause
83 any errors, and the script may choose to alter any part of the
86 If any part of the configuration fails, make sure you have these basic
87 requirements fulfilled:
90 You must have Lua installed. Much of the
92 script is written in Lua, and Yoink requires Lua as a dependency anyway.
94 You must have a working toolchain installed. This usually means you have
96 installed along with its C++ compiler components, libc and binutils.
100 installed, along with the required library dependencies and \(lqpc\(rq
101 files. Look for these packages with your favorite package manager:
114 OpenGL (including GLU)
122 Once the build system has been properly configured, it is ready to do some
123 compiling. This is done simply with an invocation of GNU make, perhaps
128 Sometimes the command for GNU make is
130 although it may also be simply
134 will work, and you need a fairly recent version of GNU make since some
135 older versions have fatal bugs. The
137 flag may be used to perform multiple build steps in parallel, decreasing
138 the amount of time the compile takes on multi-core machines. See
140 for more information.
142 Advanced users may choose to override parts of the configuration with
143 additional arguments to
145 although it is rarely useful to do so. However, in the event that some
146 error occurs during the process, it often is useful to retry the
150 argument (for verbosity) in order to cause
152 to echo each actual command before it is executed. Users who are familiar
153 with compiler and linker warnings and errors will then be able diagnose the
154 problem, whether it be a problem with the configuration or something else.
156 After the build process has successfully completed, Yoink should now be
157 able to run from within the
159 directory, as long as you're not cross-compiling to an incompatible
160 platform. To test this, there is a
162 target to execute Yoink:
166 If an error occurs and the rest of the build really did complete
167 successfully, the likely problem is that the dynamic libraries could not be
168 found. This may happen if the libraries are installed to a non-standard
169 location, and the linker wasn't given the appropriate
171 flag. This means that
173 failed to provide all of the flags we need. The easiest thing to do in
174 this situation is to reconfigure the build system with the
175 .Ar LDFLAGS=-Wl,-rpath=/path/to/lib
176 option set and retry the test (the executable will be rebuilt).
178 Once testing is completed, it is time to copy the Yoink files to their
179 final destinations. As usual, there is a
181 target to handle the installation:
185 This will cause the files to be copied with the BSD-compatible
187 program. Of course, you may need to elevate your privileges (i.e. with
189 if you are installing to a directory your user account does not have write
192 The installation destination depends on
194 and other configuration variables. You can override the configuration by
195 passing the arguments directly to
197 with the install target. The
199 also supports staging by using the
204 Any failure during installation is probably a result of simply not having
205 sufficient privileges. It will also be a problem if you do not have a
206 BSD-compatible version of
208 In the case of the latter, it should be a minor modification to the
210 to get it working. The build system is still not compatible in many
225 .Bl -tag -width 2i -compact
226 .It An Charles McGarvey
projects / chaz / yoink / blob