LOANI's corner

Three-step two-line quick guide for the impatient and the fearless UNIX OSDL end-user

Download either LOANI-0.6.zip or LOANI-0.6.tar.gz, extract it, execute ./loani.sh as your normal user to have OSDL, Ceylan and all their prerequisites automatically and safely downloaded, extracted, configured, compiled and built together for you, when targeting the PC.

If cross-compiling for the Nintendo DS, just add: --nds. If wanting only the Orge server, just use the --onlyOrgeTools option. That's all!

If wanting to build the OSDL toolchain for Windows, just refer to this document instead.

Table of contents

Overview

This is the manual page for LOANI version 0.6.

LOANI stands for Lazy OSDL's Automatic Net Installer. Its purpose is to simplify as much as possible the installation of OSDL and its prerequisites on supported platforms, notably Windows and most UNIX platforms, including GNU/Linux.

Installed developments may include, depending on the choice of the LOANI user:

• Ceylan and OSDL for native build
• Ceylan and OSDL for cross-compilation to the Nintendo DS
• Server-side Orge

We really understand that there are much more enjoyable activities than to painfully install an intricate list of, in some cases, cyclic dependencies in order to have one's library working. That's why it ought to be automated.

Some operating systems, such as GNU/Linux with for example the Debian, Ubuntu or Gentoo distributions, automate software installations with a package system. However this does not discard the need of tools like LOANI, as specific versions of helper libraries must be compiled with dedicated options. Most often package managers do not let easily choose the options sets and/or offer too old versions and/or patch them inaccurately. For example, SDL_image did not build with gcc higher than 3.4, and needs to be configured with JPEG, PNG support, but not TIFF one. LOANI takes in charge that task automatically, and without complaining.

That's why we imagined LOANI: the simplest shell script (on the user side) that performs everything on your behalf, and cooks you a brand new OSDL-compliant environment from scratch, with almost no effort but the typing of a simple line in your shell: ./loani.sh.

Its main targeted audience is the developer community. For end users, a set of platform-specific binaries will be available in the future.

Even though all the tools used are available on the most common platforms, OSDL and, notably, Ceylan, are still to be ported so that they can be executed reliably elsewhere than on Windows and on GNU/Linux. Our next targets will be the various Mac OS X flavours, so that most gamers can be reached.

LOANI is released under the GNU GPL licence.

LOANI's own prerequisites

Platforms

LOANI has been thoroughly tested first on GNU/Linux platforms, with various hardware and distributions [More info]. Even if some bugs may appear (on error, please see LOANI troubleshooting), we believe most of LOANI's users should experience a good behaviour of this tool.

The other main targeted platforms are the Windows ones (XP/Vista/Seven), using Cygwin as host environment, and Visual Express Edition (at least 2005) as compilation toolchain. Both tools are totally free.

As, on Windows, this developer environment may be a bit difficult to settle down, we wrote a small step-by-step guide to have one's build environment working. Windows users must apply it first before running LOANI.

For other platforms, some adaptations may have to be performed. A general rule of thumb is to use as much as possible GNU tools, in order to be on the safe side. We will welcome reports of tests or, even better, patches to have LOANI work on other platforms.

Other prerequisites

One of course should have a working Internet connection in order to retrieve the target packages, if needed: one could indeed pre-fetch archives thanks to any available way (ex: a CD or an USB key) and put them in LOANI's cache repository (i.e. the LOANI-repository directory), to avoid any subsequent download. Note also that we try to maintain a last-resort up-to-date FTP cache, to overcome outages of the respective official download locations (LOANI will then make automatically use of it, as a fall-back).

Tools needed for LOANI (GNU version strongly recommended)

All of them should already be available on most UNIX-like systems:

• basic UNIX tools: cp, mv, ln, rm, mkdir, grep, find, du, uname, id, ps, wc
• more advanced UNIX tools: awk, tar, gunzip, bunzip2, xz, ping, md5sum, wget
• build tools: make, cmake, automake, autoconf

For Windows-based systems, selecting most tools in the Cygwin set-up should be enough.

For Debian-based systems, this command should help to secure most of the needed packages:

For RPM-based systems like OpenSuse, this command should help:

Please note that these prerequisites are LOANI's ones plus most of the ones of OSDL and of its own prerequisites. The complementary tools should be retrieved, installed and used automatically by LOANI, if requested (ex: the C++ compiler).

What LOANI provides

LOANI is a user-friendly tool for OSDL, which can let you choose one or more tool selections and will automatically retrieve, configure, compile, install and link together the corresponding tools in their relevant versions.

All the managed tools are free software (free of charge and open source).

Only basic settings are described here: should the Nintendo DS environment be selected (thanks to the --nds command-line option), the software set would differ drastically. The toolchain would then be based on devkitARM, dlditool, libnds, PA_lib, libfat, dswifi, etc., although it would lead finally to Ceylan and OSDL as well (after quite different paths). See our tool section in our DS homebrew guide for more details.

See our Orge section for specific details about the Orge support.

Required tools selection

This tool selection is mandatory for OSDL's functioning, therefore no specific option has to be passed to LOANI to have it taken into account. Following prerequisites are managed, with dependencies shown (LOANI manages all the dependency tree, i.e. the prerequisites of prerequisites and so on):

Following first-order dependencies are selected:

• SDL: OSDL's main low level back-end
• SDL_image: a SDL helper library, allowing to support most common picture formats. Its installation involves setting up various needed libraries, such as libpng, libjpeg and zlib libraries. LOANI does that for you
• SDL_ttf: another SDL helper library, which provides Truetype font rendering thanks to FreeType, which is also managed automatically by LOANI
• SDL_gfx: yet another SDL helper library, which is convenient to scale and rotate pictures, for basic 2D primitives and low-level pixel access
• SDL_mixer: a multi-channel audio mixer which can use OggVorbis music thanks to libogg and libvorbis
• CEGUI: a toolkit for graphical applications (GUI) that can make use of OpenGL. Uses PCRE, Freetype and FreeImage
• PhysicsFS: a library to provide abstract access to various archives, so that the user cannot mess with application data too easily
• pthreads Win32: a way to have Windows being POSIX-compliant for threads (not used currently)
• libtool: GNU tool to perform builds in a cross-platform way (UNIX only). Note that this libtool version will be specifically patched, so that it stops linking libraries with the rpath set. Otherwise this would prevent distributing prebuilt OSDL libraries (see this link for further information)
• Ceylan: our generic all-purpose C++ library

OSDL is our generic multimedia library built on top of these prerequisites.

The case of the Ceylan and OSDL libraries: source archive or SVN

Ceylan and OSDL can be both retrieved thanks to a source release archive or thanks to SVN. In the first case, a compressed archive is downloaded by LOANI (as it does for other tools), whereas, for the SVN case, the corresponding source tree is retrieved, according to the chosen version (developer or end-user).

Retrieving sources thanks to SVN

Thanks to the --sourceforge <user name> option, our project developers can retrieve a fresh (coming from the cutting-edge developer SVN server) check-out version of Ceylan and OSDL, in order to have painlessly a developer-ready install, since SVN information will be managed and retrieved too. Note that this option implies the --currentSVN option, which means that the cutting edge sources are wanted, even though the build tree may be broken during development.

End-users that prefer SVN should use --useSVN instead of the two previous options. The retrieved sources will then be the result of a SVN export made from the anonymous SVN server, and no SVN meta-data will be managed. Unless the --currentSVN option is specifically set, retrieved files for Ceylan and OSDL correspond to their respective last stable versions, as determined by SVN tags (ex: STABLE_20040906). If the --currentSVN option is set, then the latest version of each file is used. This is usually unsafe during development.

Note that, as LOANI uses the SVN client provided by Cygwin, a checkout may report a success whereas it actually failed, if it resulted into too long paths. One should use TortoiseSVN after this checkout and perform an update, just to be sure all files are here.

More generally, one should avoid trying to perform any LOANI installation from a directory already too much nested in the filesystem tree (ex: in a deep directory below My Documents), as some Windows tools may fail in that case.

Build tools section

These build tools or counterparts of them (other C++ compilers, same tools with different versions) might already be readily available on user's system (it used to be seldom the case; now they are most often readily available, and in a quite recent version). If not, or if tool versions do not match the required ones, select this tool section, thanks to the --buildTools LOANI option.

Installing by oneself these build tools is quite often needed, since for example gcc often breaks downward binary compatibility for C++ base libraries: we often need a very precise version of libstdc++. As we already chose for you the latest gcc version able to build all OSDL prerequisites, relying on LOANI to install gcc and other build tools as well is a safe bet.

Note that using that option assumes that a working C compiler is already locally available on your computer, since the build tools will be themselves built from sources. However all usual GNU/Linux platforms offer that.

Moreover, building gcc now requires GMP and MPFR. One should thus ensure these packages are available beforehand. For example Ubuntu users should execute as root: apt-get install libgmp3-dev libmpfr-dev before launching LOANI.

Build tools are:

• gcc/g++: up-to-date C++ compiler
• binutils: necessary to handle one's binaries, should be built by the compiler in use
• gdb: the GNU debugger, useful to correct bugs and crashes
• Erlang: the amazing functional language for concurrency (see also our standalone installation script)
• Python: the famous python interpreter [not supported yet]

Optional tools section

These tools are not strictly needed, but are helpful for developers and/or documentation maintainers, who ought to make use of them. You can request this tool selection thanks to the --optionalTools LOANI option.

These tools are:

• doxygen: to generate html documentation from sources
• dot: needed by doxygen to generate its graphs
• tidy: useful to ensure strict W3C conformance of web pages

Orge section

The technical environment used by server-side Orge is quite different from the Ceylan and OSDL C++ main code path. Thus if LOANI is requested to install Orge (ex: ./loani.sh --onlyOrgeTools --prefix /home/orge/software), instead of the C++ toolchain, the Erlang one will be installed and used afterwards.

Note that some prerequisite packages are needed to build Erlang with our settings. For example, on Debian and Ubuntu, apt-get install gcc make libncurses5-dev openssl libssl-dev should be executed before running LOANI.

Installation and packages are more precisely described in the Orge technical manual.

Selecting all tools section

If one wants to select all the above managed tools (required, build and optional), simply use the --allTools LOANI option. The user should end up with a total installation weighing approximately 700 megabytes, if stripped down with archive cache removed. Let's remember that gigabytes are cheap (but the incurred build time might then become prohibitive).

Speaking of build duration, the whole process (retrieving all the files from the net and building all) lasts less than 90 minutes in an otherwise idle average PC with a 128 kb broadband access.

Setting the user's environment

LOANI has the ability to provide its user a developer-friendly UNIX environment. It consists on well configuring bash, some editors (nedit, vim) and some other defaults. To have one's environment updated and improved, add the --setEnv option.

Please note that all pre-existing configuration files are kept in a copy suffixed by .previous. One should therefore not loose any configuration information, since LOANI stops on error whenever there already exists a backup file in the way.

How to get it and use it

One should download either the LOANI-0.6.zip or LOANI-0.6.tar.gz archive.

Always as a normal user (using root is not recommended for the moment), after having downloaded it, one has to extract the archive, with unzip LOANI-0.6.zip or gunzip < LOANI-0.6.tar.gz | tar xvf - (note that tar -xvzf LOANI-0.6.tar.gz should work with GNU-based tar). Change now to the extracted directory: cd LOANI-0.6.

Then, to figure out the main options, one could use:

./loani.sh --help

To benefit from our embedded tiny text wizard (answer the questions and everything should go fine):

./loani.sh --wizard

Otherwise, most end-users may use directly:

./loani.sh --prefix /where/to/install/everything

whereas (registered) Ceylan/OSDL developers may use for example:

./loani.sh --prefix /where/to/install/everything --sourceforge <developerLogin>

Many users wish everything to be installed in the current working directory, and therefore do not even have to set a specific prefix.

If ever errors occured (which might happen), one may take a look at LOANI.log, a log file created in the directory from which LOANI was launched, or directly at the script itself, loani.sh (this simple script is easy to understand and customise) and/or send us a notice to have LOANI improved.

Avoiding build issues

There are often many problems coming from build tools:

• the gcc project is maybe too quick when releasing new compilers, which may have flaws or incompatibilities (ex: libgcc_s.so breaking existing builds)
• some GNU/Linux distributions sometimes mess up with compiler management (Red Hat releasing an unofficial and totally buggy gcc 2.96)
• the tools cannot catch up with frantic pace of compiler versions (ex: SDL not supporting gcc 3.4 for a few months)
• the user are too often unable to set proper build environment (ex: multiple conflicting gcc versions installed in various locations: /usr, /usr/local, and so on)
• when compilers are all right, it is often the binutils, linkers (ld) and/or libtool that are not rebuilt accordingly

For all these reasons and many others, the user build environment might not be able to behave correctly, preventing OSDL to be built. Therefore we added the --buildTools option which takes totally care of it, on the user's behalf in order not to mess up in any case with system installation. The compiler, gcc, libtool and all other tools will be in this case automatically installed and used as they should, without interfering with existing configuration.

This option, which should be used in order to be in the safe side, can be specified that way:

Note that the --allTools option implies the --buildTools option.

What LOANI should display during build

Here is a sample of what should happen:

tester@testingHost LOANI-0.6 $ ./loani.sh --allTools


		< Welcome to Loani >

This is the Lazy OSDL Automatic Net Installer, dedicated to the lazy and the fearless.

Its purpose is to have OSDL and all its prerequisites installed with the minimum of time and effort. Some time is nevertheless needed, since some downloads may have to be performed, and the related build is CPU-intensive, so often a bit long. Therefore, even with a powerful computer and broadband access, some patience will be needed.
Warning: No prefix specified and not run as root (which is recommended indeed): adding prefix /home/tester/LOANI-0.6/LOANI-installations.
Retrieving all prerequisites, pipe-lining when possible.
Target package list is <libtool SDL libjpeg zlib libpng SDL_image SDL_gfx freetype SDL_ttf libogg libvorbis SDL_mixer Ceylan OSDL>.
Some tools already available (libtool SDL libjpeg zlib libpng SDL_image SDL_gfx freetype SDL_ttf libogg libvorbis SDL_mixer CEGUI PhysicsFS), others will be downloaded (Ceylan OSDL).
Retrieving Ceylan from developer SVN with user name wondersye.
	  ----> getting Ceylan from SVN with user name wondersye (check-out)
	  <---- Ceylan retrieved [from SVN]
Retrieving OSDL from developer SVN with user name wondersye.
	  ----> getting OSDL from SVN with user name wondersye (check-out)
	  <---- OSDL retrieved [from SVN]
All prerequisites available.
	  ----> libtool    : extracting [OK] configuring [OK] building [OK] installing [OK]
	  ----> SDL        : extracting [OK] configuring [OK] building [OK] installing [OK]
	  ----> libjpeg    : extracting [OK] configuring [OK] building [OK] installing [OK]
	  ----> libzlib    : extracting [OK] configuring [OK] building [OK] installing [OK]
	  ----> libPNG     : extracting [OK] configuring [OK] building [OK] installing [OK]
	  ----> SDL_image  : extracting [OK] configuring [OK] building [OK] installing [OK]
	  ----> SDL_gfx    : extracting [OK] configuring [OK] building [OK] installing [OK]
	  ----> freetype   : extracting [OK] configuring [OK] building [OK] installing [OK]
	  ----> SDL_ttf    : extracting [OK] configuring [OK] building [OK] installing [OK]
	  ----> libogg     : extracting [OK] configuring [OK] building [OK] installing [OK]
	  ----> libvorbis  : extracting [OK] configuring [OK] building [OK] installing [OK]
	  ----> SDL_mixer  : extracting [OK] configuring [OK] building [OK] installing [OK]
	  ----> PCRE       : extracting [OK] configuring [OK] building [OK] installing [OK]
	  ----> FreeImage  : extracting [OK] configuring [OK] building [OK] installing [OK]
	  ----> CEGUI      : extracting [OK] configuring [OK] building [OK] installing [OK]
	  ----> PhysicsFS  : extracting [OK] configuring [OK] building [OK] installing [OK]
	  ----> Ceylan     : extracting [OK] configuring [OK] building [OK] installing [OK]
	  ----> OSDL       : extracting [OK] configuring [OK] building [OK] installing [OK]
Post-install cleaning of build trees.
End of LOANI, started at 19:00:44, successfully ended at 19:30:15.
You can now test the whole installation by executing /home/tester/LOANI-0.6/LOANI-installations/OSDL-0.5/share/OSDL-test/playTests.sh              

On a side note, LOANI usually have to ask some more questions. The first is:

The authenticity of host 'osdl.svn.sourceforge.net (66.35.250.207)' can't be established.
DSA key fingerprint is 02:ab:7c:aa:49:ed:0b:a8:50:13:10:c2:3e:92:0f:42.
Are you sure you want to continue connecting (yes/no)?

Answer yes to this one, it is just the SSH-powered SVN client wanting the user to acknowledge the connection to SourceForge's SVN server, whereas the user host never before had been connected to that server. That should not be a problem for anybody.

The other question is, for the registered OSDL users that chose the SVN developer access (--sourceforge option) but did not set up authentication by SSH public key on Sourceforge'side (very few happen to use them), the following:

This question may be asked more than two times (at least one for Ceylan, and one for OSDL). It is due to SourceForge's SVN servers' hiccups, LOANI will try multiple times before aborting, in the case where there is an outage of SourceForge services. Each time, answer in an appropriate way and everything should work well.

LOANI's main features

• integrated: does everything on your behalf, i.e. for all prerequisites retrieves, extracts, configures, builds, installs. No worry, nothing to do, let it work for you
• simple: one can launch LOANI just by loani.sh and let it do its best alone
• robust: we made the most careful and reliable choices, and we thoroughly tested LOANI on various platforms. We believe LOANI is rock-solid and that it should work out-of-the-box on most UNIX platforms
• highly modular: based on tool sets, selectively choosable (ex: required tools and build tools and/or optional tools)
• fast and efficient: a cache is maintained to transfer archives only once, it will not download anything if not necessary, and, when necessary, will launch multiple downloads simultaneously, to maximise bandwidth use and shorten the installation time. Limited proxy support is provided through the PROXY_CONF environment variable (bash example: export PROXY_CONF='--proxy-user=<my user name> --proxy-passwd=<my password>')
• cross-platform: more exactly, LOANI should work with no change on most UNIX platforms and on Windows platforms
• user-friendly: with multiple notification levels, a wizard mode and fancy colours. It can improve as well your environment so that it becomes developer-friendly, and takes into account your profile: end-user or developer
• secure: issues warnings or errors in case of abnormal situations, can strictly ensure md5sum checking for downloaded archives, never overwrites files if in strict mode. Does not need root privileges: if a non-privileged user launches LOANI (which is the recommended way), tools will be installed in supplied prefix directory, or, if not supplied, in current working directory under the default prefix, LOANI-installations. If root tries running LOANI, he will be prompted to confirm, since this choice is not recommended
• well documented: besides this web section, loani.sh --help gives you detailed information
• extensible: one can easily add new tool sections or upgrade existing ones. It is only a bash script, so it is quite easy to understand and maintain

Syntax reminder

This is loani.sh, the famous Lazy OSDL Automatic Net Installer.

Usage: loani.sh  [ -d | --debug ]
		  [ -s | --strict ]
		  [ -q | --quiet ]
		  [ -w | --wizard ]
		  [ -u | --useSVN ]
		  [ -c | --currentSVN ]
		  [ --sourceforge <user name> ]
		  [ --buildTools ]
		  [ --optionalTools ]
		  [ --OrgeTools ]
		  [ --onlyOrgeTools ]
		  [ --allTools ]
		  [ --nds ]
		  [ --setEnv ]
		  [ --fetchonly ]
		  [ --all ]
		  [ --prefix <a path> ]
		  [ --repository <a path> ]
		  [ --noLog ]
		  [ --noClean ]
		  [ -h | --help ]

Options:
		-d or --debug            : display debug information to screen
		-s or --strict           : be strict, stop on wrong md5 checksums or on unexpected tool locations
		-q or --quiet            : avoid being too verbose
		-w or --wizard           : enter wizard interactive mode, so that questions are asked to configure
		-u or --useSVN           : retrieve Ceylan and OSDL from SVN, instead of downloading pre-packaged source archives
		-c or --currentSVN       : retrieve current SVN for Ceylan and OSDL, instead of latest SVN tagged stable release (implies --useSVN)
		--sourceforge <user name>: uses SourceForge developer access to retrieve projects from SVN  (implies --currentSVN)
		--buildTools             : retrieve and install common build tools too (ex: gcc, binutils, gdb)
		--optionalTools          : retrieve and install optional tools too (ex: doxygen, dot, tidy)
		--OrgeTools              : retrieve and install all tools for Orge (ex: Erlang)
		--onlyOrgeTools          : retrieve and install all tools for Orge, and no other tool
		--allTools               : retrieve all tools (required, build, optional tools)
		--nds                    : set mode for cross-compilation from GNU/Linux to Nintendo DS homebrew
		--setEnv                 : set full developer environment (ex: bash, nedit configuration)
		--fetchonly              : only retrieve (download in cache) prerequisite, do not install them
		--all                    : install all and set all
		--prefix <a path>        : install everything under <a path>
		--repository <a path>    : specify an alternate cache repository for downloads
		--noLog                  : do not log installation results
		--noClean                : do not remove build trees after a successful installation
		-h or --help             : display this message

 Recommended example (long but safe): loani.sh --allTools

There exist some hidden options, i.e. undocumented in the command line help, since seldom used:

• --noSVN: do not retrieve Ceylan or OSDL from SVN, merely used for LOANI debugging (they will not be retrieved at all)
• --onlyBuildTools: only build tools will be installed
• --onlyOptionalTools: only optional tools will be installed

Troubleshooting

The most common mistakes that are made or errors that occur are listed here, alongside with their solution.

You got: ./loani.sh: /bin/bash: bad interpreter: Permission denied

Your /bin/bash is not a valid link, or it does not refer to an executable file, or you are on a partition whose noexec attribute is set (use the mount command to check, for example the user fstab attribute implies it). Finally, check that the loani.sh script was not corrupted by a transfer (for example, beware of Windows and CR/LF transformations, think to dos2unix if you have a weird transfer client), and of course that the script is still executable.

You got: "Error: XYZ archive not available through main server or known mirrors.

This may happen when a download server and all its mirrors known by LOANI are down. In the rather unlikely case where this occurs, a quick workaround is to get the missing archive by any means, to copy it in LOANI's cache, LOANI-repository if not specifically overridden, and to launch LOANI again.

LOANI seems to hang while downloading packages, notably whenever I am retrieving Ceylan and OSDL from SVN

The main culprit for that case seems to be Sourceforge's SVN which experiences some outages that lead to a never-ending check-out. A good workaround is to type CTRL-C in the terminal from which LOANI is run, it will force a SVN reset which will result in another SVN attempt of LOANI which, in most cases, then succeeds.

Another frequent cause of problem is SVN needing the user to acknowledge interactively the use of Sourceforge certificate. Using tail -f LOANI.log, one can see a message like:

Error validating server certificate for 'https://osdl.svn.sourceforge.net:443': - The certificate is not issued by a trusted authority. Use the fingerprint to validate the certificate manually! Certificate information: - Hostname: *.svn.sourceforge.net - Valid: from Oct 27 12:05:58 2006 GMT until Oct 28 13:05:58 2007 GMT - Issuer: Equifax Secure Certificate Authority, Equifax, US - Fingerprint: f2:6c:fe:bb:82:92:30:09:72:dd:1c:b3:e7:56:69:c7:7a:df:67:3e (R)eject, accept (t)emporarily or accept (p)ermanently?

Most simple work-around is to accept manually the certificate from a terminal with svn co https://osdl.svn.sourceforge.net:/svnroot/ceylan for example, to stop it once the certificate has been accepted, to remove any downloaded directory, and then to launch LOANI again.

Otherwise the issue and its solution are mostly the same as for the previous case. Typically, LOANI succeeded in downloading most packages, but, for one or more, does not progress any more. Using again tail -f LOANI.log, you may see LOANI regularly waiting for the lacking packages, and inspecting the various wget-log.* shows some messages like failed: Connection timed out.

This may happen if a download mirror is experiencing some kind of internal errors. Despite the fact that mirrors used by LOANI are selected among the major and most available ones, some outages already occured. Some temporary network failures may happen too. Most of the time LOANI overcomes these problems and defaults to the next available mirror: just wait some more seconds to let it switch to another mirror.

Otherwise, if LOANI seems really frozen (we have not experienced this behaviour for a few years now), you can download by your own means the relevant archives (for example freetype-x.y.z.tar.bz2) and move them directly into the cache directory (by default, LOANI-repository), among the other archives. Next time LOANI will be launched, it will take them into account, provided that they are not corrupted (i.e. their MD5 codes are right) or provided that strict mode is not enabled.

Still frozen (this should really almost never occur after that step)? After having waited enough (beware, some archives such as the one of gcc are very big), if the log files do not progress any more, the downloads (SVN and/or wget ones ) may encounter a network problem which happens on the user side.

Then one may stop LOANI, possibly get rid of all wget processes still running (if any), and remove partially downloaded archives in LOANI-repository (if strict mode is not chosen, since otherwise these archives would be taken as they are, next time LOANI is run).

After this cleaning, one may launch again LOANI a few moments later, and see whether networked operations are on a better route.

You got: Error: Unable to extract XYZ, aborting.

It may happen if you did not use the strict option ([ -s | --strict ]), which would have triggered sooner a fatal error when the MD5 checksum of the downloaded package was found not matching the recorded one. You must have had a non-fatal warning for that, nevertheless. This may be the sign that a download failure occured, and that the retrieved archive was corrupted. Your best bet is to delete the corresponding archive in LOANI's cache (by default, LOANI-repository) and re-launch LOANI.

You got: Unable to pre-configure JPEGLibrary, host detection failed and there is no host work-around for your platform.

This issue is due to the jpeg library, whose configure uses ltconfig, which is not always able to guess the underlying platform. We made a workaround for the most common Linux case (i686-pc-linux-gnu), but your platform has still some problems. Please send us a Request For Enhancement, we will add your platform support as soon as possible.

LOANI seems to have downloaded the right tool versions, but Ceylan or OSDL build fails while asking for older versions

This can happen if SVN is being used but --currentSVN LOANI option is not selected, and if you have bad luck.

Long story short, in the LOANI tarball there is a (often recent) version of loani-versions.sh which is the centralised place where tool versions are defined. If the --currentSVN option is not selected, then LOANI will use a SVN tag to retrieve tagged latest stable versions for all files, including a loani-versions.sh which dates back to this stable version.

It might differ from the one of the tarball, which explains why conflicts may occur. Based on the tarball, recent tools would have already been downloaded indeed, whereas the tagged code would demand older ones.

This is clearly a bug (see support), whose origin is to be found in too few stable tags being put. Adding --currentSVN to the loani.sh command line could fix it, in the lucky and most unlikely case where the SVN tree is not broken at the moment.

LOANI does not find C/C++ compilers, or finds unwanted ones

To get rid of the ambiguity between C and C++ compilers (partly due to the meaning of the CC environment variable and the allegation of gcc "able to distinguish between C and C++ sources"), LOANI will let the two environment variables C_COMPILER (for C compiler) and CPP_COMPILER (for C++ compiler) eclipse all other, including CC. If one of the two is needed and if it does not point towards a valid executable, an attempt will be made to respectively find gcc and g++. On failure, LOANI will fall back to CC, if set, hoping it will match the need.

If, as it would be normal, you are bothered by these build issues, just use the --buildTools option and let LOANI take care of it!

If your are using the --sourceforge option and LOANI fails

Check that SourceForge really granted your user the right to access the developer SVN server, thanks to:

svn https://osdl.svn.sourceforge.net:/svnroot/osdl co --username=YourSourceForgeUserName

(replace YourSourceForgeUserName by the real username you chose at SourceForge, everything should be typed on one line, most of SourceForge users will have to enter their password)

If the previous SVN check-out test succeeds, but LOANI keeps on failing with SVN

Check your entered the right password when LOANI asked it (beware of caps-locks, num-locks, of hitting backspace to correct a typo in the password instead of CTRL-H, etc.). Take also a look at the Sourceforge SVN status page, since some outages happen regularly.

LOANI stops on random steps of the installation

Check you have enough space on your hard-drive (use for instance df -k .): LOANI performs some rough size estimates, but may be wrong. If it fails and little room remains, you have your first suspect. If the space left is not guilty, and if you are using Windows, some random errors actually seem to happen when using Cygwin. We noticed that sometimes some executables are not found whereas they are here, or some md5sum checkings fail whereas the sums should match. Try to re-launch LOANI, the outcome might be more satisfying, even though we are not fond of non-deterministic software.

LOANI fails while configuring Ceylan and/or OSDL

If you have fancy compilers (for instance, gcc 2.96) or even better no C++ compiler, and if you did not select the --buildTools option (that would compile and install for you a recent gcc; by the way, please remember that a compiler is needed to compile a compiler!), expect having some trouble configuring Ceylan and OSDL.

LOANI fails while building (compiling) Ceylan and/or OSDL

Some build failures have been encountered while trying to use old compilers, such as gcc 2.95.4, which seems to have problems handling some iostream operations (ex: with istringstream). As that same compiler seems to fail compiling a more recent version of itself (namely, the bootstrap of 3.3.3), the --buildTools LOANI option might not help you. The simplest way of dealing with this issue is to upgrade first your compiler thanks to your distribution (rpm, apt-get, emerge, etc.).

On Windows with Visual Studio, a build fails with an error C2471 or LNK1140

Visual Studio seems to manage to mess with its own generated files in some cases like incremental build. Just choosing Regenerate/Rebuild all could help.

LOANI fails with: Error: Unable to pass OSDL tests

If most OSDL tests fail (inspect OSDL/trunk/test/testsOutcome.txt for No available video device), check that the user can display windows indeed, with respect to the X server (ex: test with xclock).

LOANI fails while in erlang/common/src, short of finding the kernel/include/file.hrl

You must be using a stripped-down Erlang compiler, lacking header files, like the one installed by default with Ubuntu Karmic Koala. To fix that, either request LOANI to install a custom-built Erlang environment as well by adding the --OrgeTools option (recommended), or install the erlang-dev package.

Random or unexplained LOANI failures during build

One should first check that there is still enough room on device. On Windows, one could ensure too that the installation was performed close enough to the root of the filesystem (ex: C:\LOANI-install), as various tools may fail when paths become too long.

LOANI keeps on failing and I do not know what to do

I guess it is time for you to read our support section. Note that when using the --sourceforge option (useful for developers), you retrieve the current code, whereas regularly the SVN is broken, as one could expect for in-development versions.

No OpenGL operation succeeds, despite glxinfo showing direct rendering, fails with X11 driver not configured with OpenGL

It is the sign that SDL was not built with OpenGL support, maybe because at the time of its configuration, the OpenGL set-up was not correct. One can check it by running SDL configure again, and search for this target line:

checking for OpenGL (GLX) support... yes

Getting support

Still out of luck? Still stuck with that bloody software? Nothing above helped you? Two solutions remain for the poor lonesome user:

• if he has some programming skills and still has a little courage: the first place to investigate a little more is certainly LOANI.log, the text file where all LOANI operations are logged. This file is to be found in the directory where you executed LOANI, and is very useful to be looked at, including while LOANI is running. To do so, use tail -f LOANI.log in another terminal and lines will be shown as soon as they are output. Most of the errors should be easy fixed that way, notably if one uses too the -d option (loani.sh -d [...]): in this case, more debug information will be displayed on screen. This option stands for debug mode, and ensures that LOANI is more verbose while running
• in all other cases, we guess you deserve to issue a bug report.
  • If you are running any operating system but pure (non-cygwin) Windows, please send the file created thanks to our generator of bug reports (just run it thanks to cd <where you extracted LOANI archive>; ./generateBugReport.sh and follow the instructions) to our mail account dedicated to troubleshooting, osdl-loani-bugs at lists.sourceforge.net, we will do our best to investigate and overcome the issue
  • If you are using Windows without Cygwin/MSYS/MinGW, please describe your issue, and specify what your platform is precisely and what you did. Please supply as attachment the output of LOANI (cut/paste the output lines in a text file) and LOANI.log.

We will do our best to investigate thoroughly and solve your issue. It will be an efficient feedback for us, so that we keep the documentation and the code in an always-clean state.

Please react!

If you have information more detailed or more recent than those presented in this document, if you noticed errors, neglects or points insufficiently discussed, drop us a line!