X-Git-Url: https://git.dogcows.com/gitweb?p=chaz%2Fyoink;a=blobdiff_plain;f=doc%2Fyoink_install.7;fp=doc%2Fyoink_install.7;h=c4d9c497c6c12ce34dff31f21a99bd78d796bffa;hp=0000000000000000000000000000000000000000;hb=6c9943707d4f33035830eba0587a61a34eaecbc2;hpb=af88821a172c4dfd138b91b2a5148ae50b502fa2 diff --git a/doc/yoink_install.7 b/doc/yoink_install.7 new file mode 100644 index 0000000..c4d9c49 --- /dev/null +++ b/doc/yoink_install.7 @@ -0,0 +1,228 @@ +.\" +.\" 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