+YOINK_INSTALL(7) Miscellaneous Information Manual YOINK_INSTALL(7)
-The quick and dirty instructions:
+NAME
+ yoink_install -- building and installation instructions for yoink
- ./configure
- make && make install
+DESCRIPTION
+ Yoink can usually be built and installed in the same way as most other
+ open source packages, using the following commands:
+ cd /path/to/yoink
+ ./configure
+ make && make install
-The longer, more detailed instructions:
+ Yet, although the build system scripts and makefiles follow standard
+ conventions, they are themselves a little unconventional. Therefore, if
+ things go wrong, this reference may aid in diagnosing the problem. The
+ rest of this page is for those for whom the basic steps do not work or
+ for those who have specialized needs, like packagers.
-1. Run ./configure --help to see how you can customize the installation.
+ CONFIGURATION
+ A configure script is provided in the package to help prepare the build
+ system to compile and install Yoink on your particular system. This
+ script supports many of the same options as your typical Autoconf-
+ generated script. Just use the script's --help flag to see which options
+ are available.
- If this step fails, you probably don't have Lua installed. Lua is
- required to configure the build system. It is also required by the
- built product.
+ In particular, you may use the --prefix flag to set where Yoink will be
+ installed. The default directory prefix is /usr/local, which is a good
+ idea in most cases, as long as you have write permissions for that
+ directory. Otherwise, you might want to set the prefix to be some
+ directory within your home directory.
-2. Run ./configure with whatever options you like. Use --prefix to set the
- directory where Yoink will be installed. Use --datadir to set the
- directory where the resource files will be installed. Use --host if you
- want to cross-compile for another type of system--you will need a
- working cross-compiler toolchain installed. Use CC and CXX to set the C
- and C++ compiler commands, respectively. Use CFLAGS and LDFLAGS to
- set the compiler and linker flags, respectively.
+ The script also supports the --host flag to allow for cross-compiling.
+ Use this flag to set the triplet of the machine architecture and system
+ software combination for the platform you want Yoink to run on. Of
+ course, you will need the appropriate toolchain installed.
- If this step fails, make sure you have a working toolchain (including
- compilers and archivers). Also make sure you have the required
- libraries. You also need pkg-config and all the relevant ``pc'' files
- for each library dependency.
+ If you have dialog installed, an alternative approach to configuration is
+ to use menuconfig, the interactive menu system built into the configure
+ script. To use this method, there exists a familiar make target to bring
+ up the menu dialogs:
-3. Run make. If you have a multi-core or multi-processor system, you may
- also want to use the -j option to perform compilations in parallel. See
- make(1) for more information.
+ make menuconfig
- If this step fails, you may need to change your configuration from step
- 2 and try again. In particular, you may need to change the CFLAGS and
- LDFLAGS, depending on whether it is the compiler that has a problem or
- the linker.
+ This is the same as running the configure script with the --interactive
+ flag. This allows you to browse the various options and make changes to
+ the configuration before it is saved in preparation for building.
-4. Run make run to run the program without installing.
+ Regardless of which way configure is run, it will perform various checks
+ and make sure the required dependencies are found. If all of the checks
+ pass, the configuration file is saved to config.mk, and the script will
+ terminate with an exit code of 0. If any checks fail, a non-zero exit
+ code will result. The configuration file, config.mk, can be edited
+ manually if desired. However, the configure script should be run again
+ afterward to make sure the changes didn't cause any errors, and the
+ script may choose to alter any part of the configuration.
- If this step fails, either step 3 didn't actually complete successfully,
- or there is a bug in the code that is revealed on your platform. You
- may also need to modify LDFLAGS in step 2 and try again, making sure to
- set the correct rpath so that the shared libraries will be found at
- runtime. Note that the linker will be invoked through the compiler.
+ If any part of the configuration fails, make sure you have these basic
+ requirements fulfilled:
-5. Run make install to copy the files into the installation directories you
- have specified in step 2. You're done!
+ 1. You must have Lua installed. Much of the configure script is
+ written in Lua, and Yoink requires Lua as a dependency anyway.
- If this step fails, you probably do not have correct filesystem
- permissions to install to your chosen directory. Either do the install
- with elevated privileges, or start at step 2 again and specify --prefix
- with some directory that you have write access to, such as $HOME/usr.
+ 2. You must have a working toolchain installed. This usually means you
+ have gcc installed along with its C++ compiler components, libc and
+ binutils.
+ 3. You must have pkg-config installed, along with the required library
+ dependencies and ``pc'' files. Look for these packages with your
+ favorite package manager:
+ o boost headers
+ o libpng
+ o libvorbis
+ o Lua
+ o OpenAL
+ o OpenGL (including GLU)
+ o SDL
+ o zlib
+
+ BUILDING
+ Once the build system has been properly configured, it is ready to do
+ some compiling. This is done simply with an invocation of GNU make,
+ perhaps like this:
+
+ make -j2
+
+ Sometimes the command for GNU make is gmake, although it may also be
+ simply make. No other variety of make will work, and you need a fairly
+ recent version of GNU make since some older versions have fatal bugs.
+ The -j flag may be used to perform multiple build steps in parallel,
+ decreasing the amount of time the compile takes on multi-core machines.
+ See make(1) for more information.
+
+ Advanced users may choose to override parts of the configuration with
+ additional arguments to make, although it is rarely useful to do so.
+ However, in the event that some error occurs during the process, it often
+ is useful to retry the make command with the V=1 argument (for verbosity)
+ in order to cause make to echo each actual command before it is executed.
+ Users who are familiar with compiler and linker warnings and errors will
+ then be able diagnose the problem, whether it be a problem with the
+ configuration or something else.
+
+ TESTING
+ After the build process has successfully completed, Yoink should now be
+ able to run from within the build directory, as long as you're not cross-
+ compiling to an incompatible platform. To test this, there is a make
+ target to execute Yoink:
+
+ make run
+
+ If an error occurs and the rest of the build really did complete
+ successfully, the likely problem is that the dynamic libraries could not
+ be found. This may happen if the libraries are installed to a non-
+ standard location, and the linker wasn't given the appropriate -rpath
+ flag. This means that pkg-config failed to provide all of the flags we
+ need. The easiest thing to do in this situation is to reconfigure the
+ build system with the LDFLAGS=-Wl,-rpath=/path/to/lib option set and
+ retry the test (the executable will be rebuilt).
+
+ INSTALLATION
+ Once testing is completed, it is time to copy the Yoink files to their
+ final destinations. As usual, there is a make target to handle the
+ installation:
+
+ make install
+
+ This will cause the files to be copied with the BSD-compatible install
+ program. Of course, you may need to elevate your privileges (i.e. with
+ sudo) if you are installing to a directory your user account does not
+ have write access to.
+
+ The installation destination depends on prefix and other configuration
+ variables. You can override the configuration by passing the arguments
+ directly to make with the install target. The Makefile also supports
+ staging by using the DESTDIR variable passed to make.
+
+ Any failure during installation is probably a result of simply not having
+ sufficient privileges. It will also be a problem if you do not have a
+ BSD-compatible version of install. In the case of the latter, it should
+ be a minor modification to the Makefile to get it working. The build
+ system is still not compatible in many regards.
+
+FILES
+ configure
+ config.h
+ config.mk
+ config.sed
+ Makefile
+ options.lua
+
+SEE ALSO
+ yoinkrc(5), yoink(6)
+
+AUTHORS
+ Charles McGarvey chaz@dogcows.com
+
+NetBSD 5.1.0_PATCH June 13, 2011 NetBSD 5.1.0_PATCH
projects / chaz / yoink / blobdiff