]> Dogcows Code - chaz/yoink/blob - INSTALL
fixed documentation about where to find licenses
[chaz/yoink] / INSTALL
1 YOINK_INSTALL(7) Miscellaneous Information Manual YOINK_INSTALL(7)
2
3 NAME
4 yoink_install -- building and installation instructions for yoink
5
6 DESCRIPTION
7 Yoink can usually be built and installed in the same way as most other
8 open source packages, using the following commands:
9
10 cd /path/to/yoink
11 ./configure
12 make && make install
13
14 Yet, although the build system scripts and makefiles follow standard
15 conventions, they are themselves a little unconventional. Therefore, if
16 things go wrong, this reference may aid in diagnosing the problem. The
17 rest of this page is for those for whom the basic steps do not work or
18 for those who have specialized needs, like packagers.
19
20 CONFIGURATION
21 A configure script is provided in the package to help prepare the build
22 system to compile and install Yoink on your particular system. This
23 script supports many of the same options as your typical Autoconf-
24 generated script. Just use the script's --help flag to see which options
25 are available.
26
27 In particular, you may use the --prefix flag to set where Yoink will be
28 installed. The default directory prefix is /usr/local, which is a good
29 idea in most cases, as long as you have write permissions for that
30 directory. Otherwise, you might want to set the prefix to be some
31 directory within your home directory.
32
33 The script also supports the --host flag to allow for cross-compiling.
34 Use this flag to set the triplet of the machine architecture and system
35 software combination for the platform you want Yoink to run on. Of
36 course, you will need the appropriate toolchain installed.
37
38 If you have dialog installed, an alternative approach to configuration is
39 to use menuconfig, the interactive menu system built into the configure
40 script. To use this method, there exists a familiar make target to bring
41 up the menu dialogs:
42
43 make menuconfig
44
45 This is the same as running the configure script with the --interactive
46 flag. This allows you to browse the various options and make changes to
47 the configuration before it is saved in preparation for building.
48
49 Regardless of which way configure is run, it will perform various checks
50 and make sure the required dependencies are found. If all of the checks
51 pass, the configuration file is saved to config.mk, and the script will
52 terminate with an exit code of 0. If any checks fail, a non-zero exit
53 code will result. The configuration file, config.mk, can be edited
54 manually if desired. However, the configure script should be run again
55 afterward to make sure the changes didn't cause any errors, and the
56 script may choose to alter any part of the configuration.
57
58 If any part of the configuration fails, make sure you have these basic
59 requirements fulfilled:
60
61 1. You must have Lua installed. Much of the configure script is
62 written in Lua, and Yoink requires Lua as a dependency anyway.
63
64 2. You must have a working toolchain installed. This usually means you
65 have gcc installed along with its C++ compiler components, libc and
66 binutils.
67
68 3. You must have pkg-config installed, along with the required library
69 dependencies and ``pc'' files. Look for these packages with your
70 favorite package manager:
71 o boost headers
72 o libpng
73 o libvorbis
74 o Lua
75 o OpenAL
76 o OpenGL (including GLU)
77 o SDL
78 o zlib
79
80 BUILDING
81 Once the build system has been properly configured, it is ready to do
82 some compiling. This is done simply with an invocation of GNU make,
83 perhaps like this:
84
85 make -j2
86
87 Sometimes the command for GNU make is gmake, although it may also be
88 simply make. No other variety of make will work, and you need a fairly
89 recent version of GNU make since some older versions have fatal bugs.
90 The -j flag may be used to perform multiple build steps in parallel,
91 decreasing the amount of time the compile takes on multi-core machines.
92 See make(1) for more information.
93
94 Advanced users may choose to override parts of the configuration with
95 additional arguments to make, although it is rarely useful to do so.
96 However, in the event that some error occurs during the process, it often
97 is useful to retry the make command with the V=1 argument (for verbosity)
98 in order to cause make to echo each actual command before it is executed.
99 Users who are familiar with compiler and linker warnings and errors will
100 then be able diagnose the problem, whether it be a problem with the
101 configuration or something else.
102
103 TESTING
104 After the build process has successfully completed, Yoink should now be
105 able to run from within the build directory, as long as you're not cross-
106 compiling to an incompatible platform. To test this, there is a make
107 target to execute Yoink:
108
109 make run
110
111 If an error occurs and the rest of the build really did complete
112 successfully, the likely problem is that the dynamic libraries could not
113 be found. This may happen if the libraries are installed to a non-
114 standard location, and the linker wasn't given the appropriate -rpath
115 flag. This means that pkg-config failed to provide all of the flags we
116 need. The easiest thing to do in this situation is to reconfigure the
117 build system with the LDFLAGS=-Wl,-rpath=/path/to/lib option set and
118 retry the test (the executable will be rebuilt).
119
120 INSTALLATION
121 Once testing is completed, it is time to copy the Yoink files to their
122 final destinations. As usual, there is a make target to handle the
123 installation:
124
125 make install
126
127 This will cause the files to be copied with the BSD-compatible install
128 program. Of course, you may need to elevate your privileges (i.e. with
129 sudo) if you are installing to a directory your user account does not
130 have write access to.
131
132 The installation destination depends on prefix and other configuration
133 variables. You can override the configuration by passing the arguments
134 directly to make with the install target. The Makefile also supports
135 staging by using the DESTDIR variable passed to make.
136
137 Any failure during installation is probably a result of simply not having
138 sufficient privileges. It will also be a problem if you do not have a
139 BSD-compatible version of install. In the case of the latter, it should
140 be a minor modification to the Makefile to get it working. The build
141 system is still not compatible in many regards.
142
143 FILES
144 configure
145 config.h
146 config.mk
147 config.sed
148 Makefile
149 options.lua
150
151 SEE ALSO
152 yoinkrc(5), yoink(6)
153
154 AUTHORS
155 Charles McGarvey chaz@dogcows.com
156
157 NetBSD 5.1.0_PATCH June 13, 2011 NetBSD 5.1.0_PATCH
This page took 0.038301 seconds and 4 git commands to generate.