+.\"
+.\" Copyright (c) 2009-2011, Charles McGarvey
+.\" All rights reserved.
+.\"
+.\" Distributable under the terms and conditions of the 2-clause BSD
+.\" license; see the file COPYING for a complete text of the license.
+.\"
+.Dd June 13, 2011
+.Dt YOINK_INSTALL 7
+.Os
+.Sh NAME
+.Nm yoink_install
+.Nd building and installation instructions for yoink
+.Sh DESCRIPTION
+Yoink can usually be built and installed in the same way as most other open
+source packages, using the following commands:
+.Pp
+.D1 cd /path/to/yoink
+.D1 ./configure
+.D1 make && make install
+.Pp
+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.
+.Ss CONFIGURATION
+A
+.Nm 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
+.Fl -help
+flag to see which options are available.
+.Pp
+In particular, you may use the
+.Fl -prefix
+flag to set where Yoink will be installed. The default directory prefix is
+.Pa /usr/local Ns ,
+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.
+.Pp
+The script also supports the
+.Fl -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.
+.Pp
+If you have
+.Nm dialog
+installed, an alternative approach to configuration is to use
+.Cm menuconfig Ns ,
+the interactive menu system built into the
+.Nm configure
+script. To use this method, there exists a familiar
+.Nm make
+target to bring up the menu dialogs:
+.Pp
+.D1 make menuconfig
+.Pp
+This is the same as running the
+.Nm configure
+script with the
+.Fl -interactive
+flag. This allows you to browse the various options and make changes to
+the configuration before it is saved in preparation for building.
+.Pp
+Regardless of which way
+.Nm 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
+.Pa config.mk Ns ,
+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,
+.Pa config.mk Ns ,
+can be edited manually if desired. However, the
+.Nm 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.
+.Pp
+If any part of the configuration fails, make sure you have these basic
+requirements fulfilled:
+.Bl -enum
+.It
+You must have Lua installed. Much of the
+.Nm configure
+script is written in Lua, and Yoink requires Lua as a dependency anyway.
+.It
+You must have a working toolchain installed. This usually means you have
+.Nm gcc
+installed along with its C++ compiler components, libc and binutils.
+.It
+You must have
+.Nm pkg-config
+installed, along with the required library dependencies and \(lqpc\(rq
+files. Look for these packages with your favorite package manager:
+.Bl -bullet -compact
+.It
+boost headers
+.It
+libpng
+.It
+libvorbis
+.It
+Lua
+.It
+OpenAL
+.It
+OpenGL (including GLU)
+.It
+SDL
+.It
+zlib
+.El
+.El
+.Ss 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:
+.Pp
+.D1 make -j2
+.Pp
+Sometimes the command for GNU make is
+.Nm gmake Ns ,
+although it may also be simply
+.Nm make Ns .
+No other variety of
+.Nm make
+will work, and you need a fairly recent version of GNU make since some
+older versions have fatal bugs. The
+.Fl 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
+.Xr make 1
+for more information.
+.Pp
+Advanced users may choose to override parts of the configuration with
+additional arguments to
+.Nm make Ns ,
+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
+.Nm make
+command with the
+.Ar V=1
+argument (for verbosity) in order to cause
+.Nm 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.
+.Ss TESTING
+After the build process has successfully completed, Yoink should now be
+able to run from within the
+.Pa build
+directory, as long as you're not cross-compiling to an incompatible
+platform. To test this, there is a
+.Nm make
+target to execute Yoink:
+.Pp
+.D1 make run
+.Pp
+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
+.Fl rpath
+flag. This means that
+.Nm 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
+.Ar LDFLAGS=-Wl,-rpath=/path/to/lib
+option set and retry the test (the executable will be rebuilt).
+.Ss INSTALLATION
+Once testing is completed, it is time to copy the Yoink files to their
+final destinations. As usual, there is a
+.Nm make
+target to handle the installation:
+.Pp
+.D1 make install
+.Pp
+This will cause the files to be copied with the BSD-compatible
+.Nm install
+program. Of course, you may need to elevate your privileges (i.e. with
+.Nm sudo Ns )
+if you are installing to a directory your user account does not have write
+access to.
+.Pp
+The installation destination depends on
+.Ar prefix
+and other configuration variables. You can override the configuration by
+passing the arguments directly to
+.Nm make
+with the install target. The
+.Pa Makefile
+also supports staging by using the
+.Ar DESTDIR
+variable passed to
+.Nm make Ns .
+.Pp
+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
+.Nm install Ns .
+In the case of the latter, it should be a minor modification to the
+.Pa Makefile
+to get it working. The build system is still not compatible in many
+regards.
+.Sh FILES
+.Bl -tag -compact
+.It Pa configure
+.It Pa config.h
+.It Pa config.mk
+.It Pa config.sed
+.It Pa Makefile
+.It Pa options.lua
+.El
+.Sh SEE ALSO
+.Xr yoinkrc 5 Ns ,
+.Xr yoink 6
+.Sh AUTHORS
+.Bl -tag -width 2i -compact
+.It An Charles McGarvey
+.Mt chaz@dogcows.com
+.El
projects / chaz / yoink / blobdiff