LOANI's corner

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

Download either LOANI-0.3.zip or LOANI-0.3.tar.gz, extract it, execute loani.sh --buildTools as your normal user to have OSDL, Ceylan and all their prerequesites, including the whole build chain, automatically and safely downloaded, extracted, configured, compiled and built together for you. That's all !

Table of contents

Overview

This is the manual page for LOANI version 0.3.

LOANI stands for Lazy OSDL's Automatic Net Installer. Its purpose is to simplify as much as possible the installation of OSDL and its pre requesites, on most UNIX platforms, including GNU/Linux. Human beings tend to be lazy, and we really understand there are much more enjoyable activities than to painfully install an intricate list of cyclic dependancies in order to have one's library working.

That's why we imagined LOANI : the simpliest 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 : loani.sh.

Its main targeted audience is the developer community. For end users, a set of platform-specific binaries will be available in a vague 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 elsewhere than GNU/Linux. Our next targets are Windows (notably XP) and the various Mac OS X flavours, so that most gamers can be reached.

LOANI is released under the GNU GPL license.

LOANI's own pre requesites

Platforms

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

The other main targeted platforms are Windows (98/Me/XP), using Cygwin as host environment and MinGW as compilation toolset, and Mac OSX. We will have to use both of them in a daily basis, so we expect they will be well supported soon. For the moment, the Windows build of prerequesites has been a real nightmare, so we may use cross-compilation from GNU/Linux instead.

For others 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 working on other platforms.

Other pre requesites

One of course should have a working internet connection in order to retrieve the target packages, if needed : one could indeed prefetch archives thanks to any available way (ex : a CDR or an USB key) and put them in LOANI's cache repository, to avoid any subsequent download.

Tools needed for LOANI (GNU version strongly recommended)

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

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

Please note that these pre requesites are LOANI's ones, which are a subset of full OSDL's ones. The complementary tools should be retrieved, installed and used automatically by LOANI, if requested.

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).

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 managed.

• SDL : OSDL's 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
• pthreads Win32 : a way to have Windows being POSIX-compliant for threads.
• libtool: GNU tool to perform cross-platform builds.
• Ceylan : our generic all-purpose C++ library.
• OSDL : our generic multimedia library. Of course, you need OSDL to have OSDL working !

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

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

Retriving sources thanks to CVS

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

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

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. If not, or if tool versions do not match the required ones, please select this tool section, thanks to the --buildTools LOANI option.

These build tools are 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 pre requesites, 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 offers that.

• gcc : 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
• 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.

• 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

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 300 megabytes, if stripped down with archive cache removed. Let's remember that gigabytes are cheap !

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 with a developer-friendly 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.3.zip or LOANI-0.3.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.3.zip or gunzip < LOANI-0.3.tar.gz | tar xvf - (note that tar -xvzf LOANI-0.3.tar.gz should work will GNU-based tar). Change now to the extracted directory : cd LOANI-0.3.

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

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

Otherwise, most end-users may use directly :

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

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 customize) 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 incompabilities (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 more, 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 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.3 $ ./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 pre requesites installed with the minimum of time and effort. Some time is nevertheless n
eded, 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/20051111/LOANI-0.3/L
ANI-installations.
Retrieving all pre requesites, pipe-lining when possible.
Target package list is <gcc binutils gdb dot doxygen libtool SDL libjpeg zlib libpng SDL_image SDL_gfx freetype SDL_ttf libogg livorbis SDL_mixer Ceylan OSDL>.
No tool already available in repository, will download them all (gcc binutils gdb dot doxygen libtool SDL libjpeg zlib libpng SDL
image SDL_gfx freetype SDL_ttf libogg libvorbis SDL_mixer Ceylan OSDL).
      ----> enqueuing gcc-3.4.4.tar.bz2 in download spool
      ----> enqueuing binutils-2.16.1.tar.gz in download spool
      ----> enqueuing gdb-6.3.tar.bz2 in download spool
      ----> enqueuing graphviz-2.6.tar.gz in download spool
      ----> enqueuing doxygen-1.4.5.src.tar.gz in download spool
      ----> enqueuing libtool-1.5.20.tar.gz in download spool
      ----> enqueuing SDL-1.2.9.tar.gz in download spool
      ----> enqueuing jpegsrc.v6b.tar.gz in download spool
      ----> enqueuing zlib-1.2.3.tar.gz in download spool
      ----> enqueuing libpng-1.2.8.tar.bz2 in download spool
      ----> enqueuing SDL_image-1.2.4.tar.gz in download spool
      ----> enqueuing SDL_gfx-2.0.13.tar.gz in download spool
      ----> enqueuing freetype-2.1.10.tar.bz2 in download spool
      ----> enqueuing SDL_ttf-2.0.7.tar.gz in download spool
      ----> enqueuing libogg-1.1.2.tar.gz in download spool
      ----> enqueuing libvorbis-1.1.1.tar.gz in download spool
      ----> enqueuing SDL_mixer-1.2.6.tar.gz in download spool
      ----> enqueuing Ceylan-0.2.1.tar.bz2 in download spool
      ----> enqueuing OSDL-0.3.1.tar.bz2 in download spool
      <---- libpng retrieved [libpng-1.2.8.tar.bz2]
      <---- zlib retrieved [zlib-1.2.3.tar.gz]
      <---- Ceylan retrieved [Ceylan-0.2.1.tar.bz2]
      <---- freetype retrieved [freetype-2.1.10.tar.bz2]
      <---- libjpeg retrieved [jpegsrc.v6b.tar.gz]
      <---- libogg retrieved [libogg-1.1.2.tar.gz]
      <---- doxygen retrieved [doxygen-1.4.5.src.tar.gz]
      <---- SDL_image retrieved [SDL_image-1.2.4.tar.gz]
      <---- SDL_mixer retrieved [SDL_mixer-1.2.6.tar.gz]
      <---- libtool retrieved [libtool-1.5.20.tar.gz]
      <---- libvorbis retrieved [libvorbis-1.1.1.tar.gz]
      <---- SDL_ttf retrieved [SDL_ttf-2.0.7.tar.gz]
      <---- OSDL retrieved [OSDL-0.3.1.tar.bz2]
      <---- SDL retrieved [SDL-1.2.9.tar.gz]
      <---- dot retrieved [graphviz-2.6.tar.gz]
      <---- gdb retrieved [gdb-6.3.tar.bz2]
      <---- binutils retrieved [binutils-2.16.1.tar.gz]
      <---- gcc retrieved [gcc-3.4.4.tar.bz2]
      ----> enqueuing SDL_gfx-2.0.13.tar.gz in download spool
      <---- SDL_gfx retrieved [SDL_gfx-2.0.13.tar.gz]
All pre requesites available.
      ----> gcc         : extracting [OK] configuring [OK] building [OK] installing [OK] 
      ----> binutils    : extracting [OK] configuring [OK] building [OK] installing [OK] 
      ----> gdb         : extracting [OK] configuring [OK] building [OK] installing [OK] 
      ----> dot         : extracting [OK] configuring [OK] building [OK] installing [OK] 
      ----> doxygen     : extracting [OK] configuring [OK] building [OK] installing [OK] 
      ----> 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] 
      ----> 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 23:22:33, successfully ended at 00:39:03.
You can now test the whole installation by executing /home/tester/20051111/LOANI-0.3/LOANI-installations/OSDL/OSDL-0.3/bin/playTests.sh

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

The authenticity of host 'cvs.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 CVS client wanting the user to acknowledge the connection to SourceForge's CVS 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 CVS developer access (--sourceforge option) but did not set up authentification by SSH public key on Sourceforge'side (very few happen to use them), the following :

This question may be asked more than two times (one for Ceylan, one for OSDL). It is due to SourceForge's CVS 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 pre requesites : retrieve, extract, configure, build, install. 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 thoroughfully 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 chosable (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 download simultaneously, to maximize 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. A first attempt of port to the Windows platform has been performed, based on Cygwin and MinGW, but remains partial due to libtool issues. Within a few months, we hope the Mac OSX platform will be supported.
• user-friendly : with multiple notification levels, a wizard mode and fancy colors. 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 overwrite files if in strict mode. Does not need root privileges : if a non-privileged user launchs 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 informations.
• extensible : one can easily add new tool sections or upgrade existing ones. It is only a bash script, so it is 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 | --useCVS ] [ -c | --currentCVS ] [ 
-sourceforge <user name> ] [ --buildTools ] [ --optionalTools] [ --allTools] [ --setEnv ] [ --fetchonly ] [ --all ] [ --prefix <a
path> ] [ --repository <a path> ] [ --noLog ] [ --noClean ] [ -h | --help ]


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

Options :
        -d or --debug             : display debug informations 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 --useCVS            : retrieve Ceylan and OSDL from CVS, instead of downloading prepackaged source archives
        -c or --currentCVS        : retrieve current CVS for Ceylan and OSDL, instead of latest CVS tagged stable release (implies --useCVS)
        --sourceforge <user name> : uses SourceForge developer access to retrieve projects from CVS  (implies --currentCVS)
        --buildTools              : retrieve and install common build tools too (ex : gcc, binutils, gdb)  
        --optionalTools           : retrieve and install optional tools too (ex : doxygen, dot, tidy)
        --allTools                : retrieve all tools (required, build, optional tools)
        --setEnv                  : set full developer environment (ex : bash, nedit configuration)
        --fetchonly               : only retrieve (download in cache) pre requesite, 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 :

• --noCVS : do not retrieve Ceylan or OSDL from CVS, 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), 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 overriden, and to launch LOANI again.

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

The main culprit for that case seems to be Sourceforge's CVS 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 CVS reset which will result in another CVS attempt of LOANI which, in most cases, then succeeds.

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 anymore. Using 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 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 anymore, the downloads (CVS 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 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 CVS is being used but --currentCVS 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 centralized place where tool versions are defined. If the --currentCVS option is not selected, then LOANI will use a CVS 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 --currentCVS to the loani.sh command line could fix it, in the lucky and most unlikely case where the CVS tree is not broken at the moment.

LOANI does not find C/C++ compilers, or finds not the wanted 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 CVS server, thanks to :

export CVS_RSH=ssh ; cvs -d:ext:YourSourceForgeUserName@cvs.sourceforge.net:/cvsroot/osdl co OSDL/OSDL-0.3/src/versions.inc

(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 that test fails, you might well be in the case described in "Project CVS Service: Impacted by Known Issue" : There is an outstanding issue whereby upon user addition to a project or new project creation, the user is not given permission to access the CVS and shell services. We are currently investigating the cause of the issue, however a workaround is available from the SR link that follows. As a side effect of one of our resolution attempts, a small number of user accounts that were already existing are having similar issues (the LDAP re-import killed their password), so resetting the password will fix those too.

In a nutshell, the workaround is simple : it has been found that the user can self-resolve the issue by changing their password and waiting a small amount of time for the password change to go through. Changing the password (even to the same password as it is currently set) seems to fix the issue for most users. The only thing to be aware of is that the password should contain only letters and numbers to ensure proper password interpretation on all systems. To change your password, do the following:

1. Log into the SourceForge.net website
2. Click the 'Account Options' link
3. Click the '[Change Password]' link
4. Fill out the form and click on the 'Update' button

See this for more details.

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

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 CVS 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. The solution is however simple : edit their GNUmakevars.inc (which are directly under their src directory) and update the GCC_ROOT variable with whatever path your gcc compiler is installed under (ex: to use /usr/local/bin/gcc, define GCC_ROOT=/usr/local).

For Intel C++ users, check COMPILER_FAMILY to set the compiler family (icpc), and CPP_COMPILER for the actual location. For users of other compilers, add a new compiler family in the same way the gcc and icpc families are defined, and set accordingly your COMPILER_FAMILY and CPP_COMPILER environment variables.

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 most simple way of dealing with this issue is to upgrade first your compiler thanks to your distribution (rpm, apt-get, emerge etc.).

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

I guess it is time for you to read our support section.

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, 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 informations 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, loani-bugs at esperide.com, 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 thoroughfully and solve you 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 informations more detailed or more recent than those presented in this document, if you noticed errors, neglects or points insufficiently discussed, drop us a line!