How to compile UltraStar Deluxe using the Makefile

You will only need this tutorial when either no package for your system is available or you want to set up everything so you can easily follow the progress that is made by the developers. So this page documents the whole process how to compile the source from scratch, means we start by obtaining the source and end up with a with not configured but working UltraStar Deluxe.

This is the compiler used for the USDX sources. Use either FPC 2.2.4, 2.2.2 or 2.2.0.

In Debian-based distributions, to make sure you get all needed libraries:

apt-get install fp-compiler fp-units-base fp-units-misc fp-units-fcl fp-units-i386 fp-utils

Or for the lazy, these are all packages you need:

apt-get install fp-compiler fp-units-base fp-units-misc fp-units-fcl fp-units-i386 fp-utils libsdl1.2-dev libsdl-image1.2-dev portaudio19-dev libsqlite3-dev libfreetype6-dev libavcodec-dev libavformat-dev libswscale-dev

Getting FPC

yum install fpc

For the lazy

yum install fpc SDL-devel SDL_image-devel freetype-devel portaudio-devel sqlite-devel ffmpeg-devel

Note: For this to work you need to have the RPMFusion repository enabled.

If you want to install FPC seperately call:

USE="source" emerge fpc

Please note: If you want to use Lazarus IDE (www.lazarus.freepascal.org) as editor for the sources, you might have to install a certain version of FPC that works with Lazarus. So please check the dependencies of Lazarus before you install FPC.

SuSE 10.3 1-click install [ fpc - fpc-src ]
Or by zypper:

sudo zypper ar http://mirror.geht-schon.de/packman.links2linux.de/suse/10.3/ Packman
sudo zypper ar http://download.opensuse.org/repositories/devel:/languages:/pascal/openSUSE_10.3/ Education:/desktop
sudo zypper in fpc fpc-src  SDL SDL-devel SDL_image SDL_image-devel freetype2 freetype2-devel portaudio portaudio-devel sqlite3 sqlite-devel

SuSE 11.0 1-click install [ fpc - fpc-src - fpc-debugsource ]
Or by zypper:

sudo zypper ar http://mirror.geht-schon.de/packman.links2linux.de/suse/11.0/ Packman
sudo zypper ar http://download.opensuse.org/repositories/Education:/desktop/openSUSE_11.0/ Education:/desktop
sudo zypper in fpc fpc-src  SDL SDL-devel SDL_image SDL_image-devel freetype2 freetype2-devel portaudio portaudio-devel sqlite3 sqlite-devel libffmpeg-devel

Fetch the sources from http://www.freepascal.org

• SDL (Simple Direct Media Layer, a cross-platform multimedia library)
  • URL: http://www.libsdl.org
  • Package-names:
    • Debian: libsdl1.2-dev
    • Gentoo: media-libs/libsdl
    • Fedora: SDL-devel
• SDL-image (An image file loading library)
  • URL: http://www.libsdl.org/projects/SDL_image
  • Package-names:
    • Debian: libsdl-image1.2-dev
    • Gentoo: media-libs/sdl-image
    • Fedora: SDL_image-devel
• FreeType (A Free, High-Quality, and Portable Font Engine)
  • URL: http://www.freetype.org
  • Package-names:
    • Debian: libfreetype6-dev
    • Gentoo: media-libs/freetype
    • Fedora: freetype-devel
• OpenGL (A Plattform independant graphics library)
  • URL: http://www.opengl.org
  • Info: Provided with your ATI or NVidea graphics drivers, Mesa is not recommended because of the missing hardware acceleration.
• Portaudio (A plattform independant library for audio in- and output)
  • URL: http://www.portaudio.com
  • Version: >=19
  • Package-names:
    • Debian: portaudio19-dev (not libportaudio2)
    • Gentoo: media-libs/portaudio (>=19 not in the official portage tree, you can use the ProAudio overlay and unmask maybe something link ”<media-libs/portaudio-9999”)
    • Fedora: portaudio-devel
• SQLite (SQL Database Engine with file-support)
  • URL: http://www.sqlite.org
  • Version: 3.x.y
  • Package-names:
    • Debian: libsqlite3-dev
    • Gentoo: dev-db/sqlite
    • Fedora: sqlite-devel
• FFmpeg (Video and audio encoder/decoder)
  • URL: http://ffmpeg.mplayerhq.hu
  • Package-names:
    • Debian: libavcodec-dev libavformat-dev
    • Gentoo: media-video/ffmpeg
    • Fedora: ffmpeg-devel (Only in RPMFusion repository)

• ProjectM (A library for audio visualization)
  • URL: http://projectm.sourceforge.net
  • Package-names:
    • Debian: (libprojectm-dev) (Is 1.01 in Debian unstable)
    • Gentoo: media-libs/libprojectm
    • Fedora: libprojectM-devel
• Portmixer (Audio-mixer control for Portaudio)
  • URL: http://audacity.sourceforge.net
  • Info: part of Audacity and not supported by USDX at the moment
  • Package-names:
    • No packages available (you have to fetch audacity and extract the files, so do not bother with this at the moment)
• Swscale (A fast software video scaler)
  • Info: Part of newer FFmpeg versions compiled with GPL. The LGPLed version misses this one.
  • Package-names:
    • Debian: libswscale-dev
    • see FFmpeg

In contrast to previous versions of USDX you will not need extra Pascal headers for your libs anymore. All required Pascal headers (like Jedi-SDL for SDL) come with the USDX sources. A withdraw of this solution is that one of them might not match to your lib's version but that is a general problem with Pascal because we had to port some of the C header-files ourselves.

The linux port of USDX is in an alpha state at the moment. We do not consider it to be stable or to work for you. Just compile USDX for testing or debugging purposes but not if you just want to play the game.

There is no stable branch in our SVN repository that can be used on linux at the moment so you have to use our trunk. The trunk is the current development repository and is undergoing massive changes, so it is quite possible that the trunk is not compilable at the moment. We usually compile and test the stuff before we commit any code, but because of the many possible configurations of compilers (Delphi, FPC), platforms (Windows XP/Vista, Linux, MacOSX) and libs (especially FFmpeg) it is very easy to break the code with a single commit. So we beg for pardon if this applies to you.

To access our source repository you will have to download and install subversion first.

Debian:

sudo apt-get install subversion

Gentoo:

emerge dev-util/subversion

or get it directly from the official subversion website http://subversion.tigris.org/.

The following will fetch the trunk into a folder ultrastardx in your current working directory:

svn co http://ultrastardx.svn.sourceforge.net/svnroot/ultrastardx/trunk ultrastardx

In the next sections we assume that you checked out your working copy to the ultrastardx directory.

Change to the ultrastardx directory and type:

./configure
make

If you just want to test the game you do not have to install it.
Simply start it with:

./game/ultrastardx

Although you do not have to, you may want to install the game.
You first have to obtain root user privileges (normally with su).
Then type:

 make install

On many systems configure uses /usr/local as default prefix for installation, so the executable will be copied to /usr/local/bin and data to /usr/local/share. If /usr/local/bin is not in your search path, you might want to change the prefix to /usr to copy the executable to /usr/bin and data to /usr/share instead.
To achieve this, type:

./configure --prefix=/usr
make
make install

Now you can start the game with:

ultrastardx

Soon start-menu entries for USDX will be added to kde and gnome so you will not have to start a console each time you want to play the game.

If you encounter an error with configure most probably you did not install a required package or a wrong version of it. See section (1.2) Libraries on the required libraries.

If you are certain you installed the correct version then pkg-config might not be able to find the library. We use pkg-config to determine if a lib is installed, where it is located and what version is installed. Although there are alternative ways to do so - like checking the C-header files or linking to the shared library - we consider pkg-config to be the best solution at the moment.

First check if you have a pkg-config file (suffix is .pc) for the package that was not found. pkg-config files should be present in one of the pkg-config search directories (e.g. /usr/lib/pkgconfig). If the pkg-config file is present but not in the standard search path you may add its directory by prepending PKG_CONFIG_PATH=mylibs_dir/pkgconfig/ to your configure call. See the man-page on pkg-config for further information.

Some linux distributions do not provide a .pc-file with the default package so you might have to install a special dev-package instead.

As an alternative you may want to define the package-location and options yourself without using pkg-config. Use the –with-PACKAGE=nocheck (replace PACKAGE with the name of the library) and define all PACKAGE_[…] environment variables listed by ./configure –help. For example, you might have projectM 1.1 installed into /usr/local/… but for any reason, you do not have a libprojectM.pc in /usr/local/lib/pkgconfig (a very odd case, normally you should reinstall projectM in this case!). You can call configure with this line:

./configure --with-libprojectM=nocheck libprojectM_VERSION='1.10' libprojectM_INCLUDEDIR="/usr/local/include" libprojectM_DATADIR="/usr/local/share/projectM"

A very long command but it works. For most packages only PACKAGE_VERSION must be specified or not even this. If the linker does not find the dynamic so-lib because ”/usr/local/lib” is not in your linker (ld) search-path you might have to add LDFLAGS=-L/usr/local/lib to your configure-call. If linking works but the library is not found while running UltraStar DX you have to define LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib before you call the executable. Alternatively you can pass LDFLAGS=-rpath=/usr/local/lib to configure, this will add the path to the executable's library search-path. This might be necessary too for non-standard directories using pkg-config.

configure and make offer you several options to adjust paths and features.
To list all available configure options, type

./configure --help

make release:
starts a release-build (optimized and without debug-info) once. If “make” is called afterwards the standard build defined by configure is performed.

make debug:
starts a debug-build (non-optimized with debug-info) once. If “make” is called afterwards the standard build defined by configure is performed.

make install:
installs binaries and data into their destination directories. Those depend on whether the global (default) or local build was defined with configure (see –enable-global/local).

make uninstall:
reverts “make install” and removes all previously installed data for USDX.

make clean:
removes compiled data (*.ppu *.o, …) and other data generated by make.

make distclean
like make but additionally removes data generated by configure. Used to prepare the directories for distribution.

PFLAGS:
Flags passed to FPC. If this one is defined when calling make (e.g. make PFLAGS=”-Fimyinclude”) all flags determined by configure are overriden. In the previous example only -Fimyinclude is passed to FPC. By default PFLAGS is the concatenation of PFLAGS_BASE, PFLAGS_EXTRA and PFLAGS_DEBUG/RELEASE (depending on the standard build type).
PFLAGS can be specified by configure too.

PFLAGS_BASE:

Flags passed to FPC that are common to the release and debug build like -Si or -S2. These are appended to the configure PFLAGS and cannot be changed by configure. If you do not want to use them, specify the PFLAGS environment variable directly when calling make or set PFLAGS_BASE=”” with make.
PFLAGS_BASE cannot be specified by configure.

PFLAGS_DEBUG:
Debug specific flags like -gl for genration of debug-info.
PFLAGS_DEBUG can be specified by configure too.

PFLAGS_RELEASE:
Release specific flags like -O2 for optimizations.
PFLAGS_RELEASE can be specified by configure too.

PFLAGS_EXTRA:
Additional flags passed to FPC. These flags are appended to the PFLAGS determined by configure.
PFLAGS_EXTRA can be specified by configure too.

LIBS:
Static/dynamic libraries linked with USDX in the linking stage (using ld). Must be preceded by a ”-l”, e.g. ”-lavcodec” for libavcodec. Library directories can be passed to using the ”-L” flag (-L/usr/local/lib). This may require an additional -rpath=/usr/local/lib parameter for LDFLAGS. Note: LIBS and LDFLAGS parameters are merged so it does not really matter if a linker parameter is specified in LIBS or LDFLAGS.
LIBS can be specified by configure too.

LDFLAGS:
Flags passed to the linker, for example -rpath. See LIBS too. Note: LIBS and LDFLAGS parameters are merged so it does not really matter if a linker parameter is specified in LIBS or LDFLAGS.
LDFLAGS can be specified by configure too.

USDX is build without debugging symbols and with optimizations by default. If you want to debug the code you will first have to append the debug-symbols and turn optimizations out.

Just call ./configure —-enable-debug to do so. If you passed additional parameters to configure before you will have to pass them again. As an alternative you can call make debug to build in debug-mode once.

We suppose to use gdb or a frontend for gdb to debug the code. If gdb is not installed yet you will have to do this first. Note that —-enable-debug only appends debug-symbols for gdb-compatible debuggers and not for valgrind or DWARF. See the fpc-manpage for the necessary compiler-flags to use these debuggers. If you already have a Lazarus project-file you might want to use lazarus instead of gdb directly. With Lazarus you can easily define break-points or watch a variable's contents.

To start the debugger, call

gdb ultrastardx

At the gdb-prompt type (without the (gdb))

(gdb) run

to start the game.

If USDX crashes gdb will break USDX's execution and wait for a command. Normally it is helpful to show the backtrace of the stack to see which functions were called before USDX crashed. Type

(gdb) info stack

or

(gdb) backtrace

to show the backtrace. Please submit this information if you need support from the USDX developers.

There are many other features gdb supports, type

(gdb) help

for an overview.

If you want to dig in a little deeper read gdb's info-file (info gdb) or read a good tutorial on gdb.

If you want to contribute to USDX you may contact us at our IRC channel. Either with our webfrontend or with your own irc-client (channel #ultrastardx on QuakeNet.org). If you want to get support please do not post a bug-report to a bug-tracker. Leave an entry at our forum-site on the linux-build instead. It is more important to get USDX working at the moment than to fix crashes that might be fixed already. This does not mean that we are not interested in your experiences with the linux-build.

1. • Question:
     • I can hear my own music-files in the preview- and sing-screen but do not hear the in-game sounds e.g. after entering or leaving a screen.
   • Answer:
     • Check if you copied the sound-files from the directory Sound of the 1.0.1 branch to the Sound directory of your working copy of 1.1
2. • Question:
     • My input-device is not listed in the record-options screen.
   • Answer:
     • This problem might occur if the device could not be opened by PortAudio. Check if you really need that device or if you can use another one. On some computers ALSA lists several audio-devices which do not work (that is the reason why they are not listed in USDX). For example the devices “Intel ICH… MIC” and “Intel ICH… MIC2” are not usable (and no other program is able to use them) but “Intel ICH…” and “Intel ICH… ADC” can be used for mic-input capturing. This is rather a general ALSA problem than a problem with USDX or PortAudio. Cross-check with Audacity (which uses PortAudio too) - or another program that provides input-capture capabilities - if it is able to open a device that is not listed in USDX. If Audacity is not able to do so, it is a problem with PortAudio or ALSA (or whatever soundserver you use). Otherwise, if recording works nicely on the device, it is most probably a problem with USDX. In this case you may report those problems at the IRC channel or in our USDX linux forum-site.
3. • Question:
     • There is just one input-source available for my input-device. How can I change the source?
   • Answer:
     • Input-source selection is handled by Portmixer which is a part of Audacity and is not distributed seperately. Portaudio itself is not able to switch the input-source. Portmixer is not used by default in linux and it is difficult to compile USDX with Portmixer support at the moment. So it is easier to select the input-sources and their volumes with your mixer program (e.g. AlsaMixer or KMix).
4. • Question:
     • I use KMix to change the input volume of my mic input-source but the volume does not change.
   • Answer:
     • Make sure you selected the input-source as capture-source (a little red lamp that must be lit, the green one is just for audio output) and that - in case you use a mic-source - the mic-boost is switched on. If it still does not work then it might be a problem with KMix which occurs with at least some versions or configurations. With an ALSA soundserver it shows volume-sliders for some input-sources (like the mic-input) that do not handle volume control directly. In these cases there should be a seperate (virtual) input-source named “capture” which can be used to set the input-volume. Note that this source must be selected as input-source (red indicator) in addition to the real input source (e.g. mic). In some cases due to a bug in KMix this capture volume-slider does not work as expected (the volume-setting is not applied). Use AlsaMixer (a console program) or gamix instead, they handle input selection and volume control much better than KMix.
5. • Question:
     • USDX crashed and I want to debug the code. What do I have to do?
   • Answer:
     • See section 4
6. • Question:
     • USDX crashed, should I issue a bug-report on the sourceforge bug-tracking site of USDX?
   • Answer:
     • Please do not send a bug-report. This is an alpha version and we already know of several crashes. In addition we might have fixed the issue already but didn't check the changes into SVN because of some other changes that might crash USDX. The bug-tracker at the project-site is meant for stable releases and not for alpha or beta versions. This does not mean that we are not interested in your experiences. If you need support you can leave an entry at the linux support page.
7. • Question:
     • Compiling fails with the message, that some FPC unit (libc, pthreads, etc.) was not found. But they exist in my FPC directory (/usr/lib/fpc/2.2.0/units/i386-linux/).
   • Answer:
     • Make sure you have a proper FPC configuration file (normally /etc/fpc.cfg). In addition a wrongly configured .fpc.cfg (you may rename it if you have one) in your home directory might overwrite the settings in /etc/fpc.cfg. Maybe a configuration file of an older FPC version might not have been removed correctly. In these cases, compiling might work as root but not as normal user. But instead of compiling as root, rather fix the config file, please.
8. • Question:
     • Make tells me that some file (e.g. libpzlib.a) could not be written to ./build/linux/fpc.
   • Answer:
     • Maybe UltraStar Deluxe was compiled or configure by the root user and now you are trying to compile it as normal user. In this case some directories might miss the correct privileges. Check the privileges and change them (chown/chmod) if they are not correct.
9. • Question:
     • While running ./autogen.sh it gives me some error message: ”configure.ac:<line>: error: possibly undefined macro: AC_…”. Executing ./autogen.sh a second time works but ./configure fails with ”checking for libpng… ./configure: line 4349: syntax error near unexpected token `libpng,' ./configure: line 4349: ` PKG_CHECK_EXISTS(libpng,'”.
   • Answer:
     • Most probably you do not have pkg-config installed so autoconf does not find the pkg-config macros. Install pkg-config and restart the build-process with ./autogen.sh etc.
10. • Question:
      • Building USDX was successful. But executing UltraStarDeluxe or UltraStar crashes.
    • Answer:
      • If you compiled USDX yourself the binary name should be ultrastardx instead of UltraStarDeluxe or UltraStar as in previous releases. So you might have accidentally executed an older version instead of the current one. In addition, note that with the global build you have to call make install to install the binary to the target path. If you use the local build the binary will stay in your build-directory. So if you typed ultrastardx you might have called a previously installed global version. With the local build you have to execute USDX with ./ultrastardx (note the ./) or ../ultrastardx depending on your current working directory.