Dogcows Code - chaz/yoink/blob - 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