X-Git-Url: https://git.dogcows.com/gitweb?p=chaz%2Fyoink;a=blobdiff_plain;f=INSTALL;h=b34de476ceb4b355c0ba9ababd494f98e80ad571;hp=a9438a116b123d002a13075ce920f62531dbb09f;hb=6c9943707d4f33035830eba0587a61a34eaecbc2;hpb=af88821a172c4dfd138b91b2a5148ae50b502fa2 diff --git a/INSTALL b/INSTALL index a9438a1..b34de47 100644 --- a/INSTALL +++ b/INSTALL @@ -1,53 +1,157 @@ +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