Here you will find an example setup that can be used for G System development. It is by no means the one and only possible setup, but you may find the instructions helpful to set up your own environment. The final setup will be useful for both working on the source code as well as documentation. You will also be able to run a local XMPP server to use for the G Universe Server and the G Universe Client and have a database set up. This makes it possible to perform all development related activities on a single host that does not even need to be connected to the internet.
Please note that not every step is discussed in detail. You should have some basic knowledge to be able to deal with your operating system. This is intentional, you should have to think yourself to get aquainted with the system, which will help you a lot for the actual development work itself that you will do. If you think something important is missing from these instructions or something is simply wrong, please contact the G System team.
The overall setup that is presented uses NetBSD together with pkgsrc. With this it is rather easy to install all required packages, you basically only need to know what you need. The advantage of pkgsrc is that it works on many different unix-like operating systems, not just NetBSD, so you could use pkgsrc for whatever operating system you're using. You can find details on supported platforms on the pkgsrc website - http://www.pkgsrc.org.
After installing all required packages we will take a look at tweaking the environment to suit your needs - environment variables, database configurations, importing the project into KDevelop and other things.
If possible you should have a spare computer to do the actual installation on. If that is not possible for you, partitioning the hard disk might serve your needs.
All system related configurations must be performed as super user (root) of course.
At the time of writing the available versions were in general NetBSD 3.0, xorg 6.9.0, PostgreSQL 8.0 and 8.1, Qt 4.1, Jabberd 2.0s10 and G System pre-0.6 (svn trunk).
The first thing to install is the operating system, NetBSD in this case. I'm not going to duplicate any documentation, so just take a look at the NetBSD documentation to get yourself a working installation: http://www.netbsd.org/guide/en/.
After you have successfully installed NetBSD (wasn't that easy after all? Just putting in the CD and walking through the multilinugal setup...), you should install pkgsrc. Have a look at the documentation on how to do this: http://www.netbsd.org/Documentation/pkgsrc/.
Currently it is recommended to use the latest CVS version of pkgsrc, only this includes the required Qt 4. As an alternative, you can manually install the latest Qt version yourself. Please note that at the time of writing, pkgsrc does not yet provide the PostgreSQL database plugin for Qt 4. You can also use the SQLite plugin, which is available. You could also download and install Qt yourself, this way you can install all database plugins you want, including PostgreSQL.
After installing pkgsrc, you should edit /etc/mk.conf to set some options, I have found the following useful:
ACCEPTABLE_LICENSES+=lame-license PKG_OPTIONS.jabberd2=pam pgsql PGSQL_THREAD_SAFETY=yes X11_TYPE=xorg
Please note that this uses xorg as the X11 server, you might have other preferences. The lame-license is required for the lame mp3 encoder, which in turn is required for kdemultimedia, in case you want a full K Desktop Environment. Also note that we use the pgsql option for jabberd2, which is different from the default, which is mysql. But we will use pgsql for all our database needs (three databases in total).
With pkgsrc you can install a package just by typing make install in the directory of the desired package. This list is hopefully somewhat complete, please tell us if you think something is missing.
packages to install from pkgsrc:
textproc/docbook-xsl
textproc/libxslt
devel/doxygen
databases/postgresql81
meta-pkgs/xorg
meta-pkgs/kde3
chat/jabberd2
devel/kdevelop
x11/qt4
x11/qt4-pgsql (does not exist at the time of writing)
devel/subversion-base
Some of these packages require you to install rc scripts. The install procedure will tell you to do so. Make sure you don't miss to do this. In particular this applies for the PostgreSQL and the Jabberd2 packages.
You will find all the required rc scripts in /usr/pkg/share/examples/rc.d/. The ones you need to copy to /etc/rc.d/ are:
pgsql
kdm
jabberd
c2s
sm
s2s
router
resolver
After installing all the packages, there are a few things you should do with your fresh installation to make NetBSD suit your needs.
The first thing to configure is your graphical environment - the X server. pkgsrc installs the xorg package into /usr/pkg/xorg by default. Usually we want to have the X11 installation in /usr/X11R6. but this directory is used by the NetBSD X11 server. We can just delete that and then make that a link to the xorg directory:
rm -rf /usr/X11R6 ln -s /usr/pkg/xorg /usr/X11R6
After that you can just run xorgcfg to create a configuration, save the configuration in /etc/X11/xorg.conf.
After the file has been saved, edit it and look for GLX. You should enable (uncomment) the line that says Load "glx". This is needed for OpenGL support in the X Server. If your system provides DRI, just enable that, too.
If xorgcfg does not work, just run xorgconfig.
Note: the xorg project is planning a next protocol version, so X11R6 might be replaced by X11R7 in the above instructions.
Another important thing is to have correct permissions for the communication directories for xorg, created on startup. For this put the following into /etc/rc.local:
mkdir -p -m 1777 /tmp/.ICE-unix mkdir -p -m 1777 /tmp/.X11-unix
You should create an user account to use for the G System development, have a look at the useradd command. After creating the user, run passwd <username> to set a suitable password.
By default NetBSD does not run any desktop environment at all - a shell is all it needs for many systems. Still, we want to run a graphical environment.
There are more possibilities:
put startkde into $HOME/.xinitrc,
run the K Display Manager (KDM) that gives you a graphical login screen on startup. This can either be done with the kdm rc script, or by using rc.local
To use the rc.local script, edit the file /etc/rc.local and add the following lines at the end (but before the last echo):
echo "Starting the K Display Manager (kdm)" /usr/pkg/bin/kdm
/etc/rc.local is basically a shell script that is run at boot time after the system rc scripts were run. So it is the last script run at startup. With all this in place, KDM will greet you on system startup. Choose the correct session type from the menu and log in as your user.
I found it useful to put various environment variables into my $HOME/.profile file.
A very useful variable is LD_LIBRARY_PATH. To avoid the need of installing the G System, this variable can be used to point to the location of the compiled libraries. Thus it is possible to start the compiled G System binaries without the need to install the libraries into the system. So everything can stay in the development tree.
Other variables include variables used for Qt and path settings.
I found the following content in $HOME/.profile useful:
PATH=$HOME/bin:/bin:/sbin:/usr/bin:/usr/sbin:/usr/X11R6/bin:/usr/pkg/bin
PATH=${PATH}:/usr/pkg/sbin:/usr/games:/usr/local/bin:/usr/local/sbin
QTDIR=/usr/pkg/qt4
QMAKESPEC=netbsd-g++
PATH=$QTDIR/bin:$PATH
LD_LIBRARY_PATH=/home/raphael/devel/G/trunk/lib:/usr/X11R6/lib
export PATH QTDIR QMAKESPEC LD_LIBRARY_PATH
EDITOR=vi
export EDITOR
Please note that these settings are only useful for shells that evaluate $HOME/.profile. I would recommend you to use bash. You can find it in pkgsrc as well, if it's not already installed. Note, you can use vipw to set the login shell.
Additionally, the LD_LIBRARY_PATH variable expects the G System development sources to be in $HOME/devel/G.
PostgreSQL is a fully featured, robust ORDBMS (Object Relational Database Management System). It is the most advanced free DBMS available. Look at http://www.postgresql.org for details and documentation.
PostgreSQL is needed for the following databases:
jabberd2 authentication
G Universe Server database
G Universe Client database
First, make sure you have copied the pgsql rc script to /etc/rc.d/pgsql. If not, look above.
With this in place, add pgsql=YES to your /etc/rc.conf file.
Then run the PostgreSQL server: /etc/rc.d/pgsql start
# su pgsql $ createuser jabberd2 $ createdb -O jabberd2 jabberd2 $ exit # cd /usr/pkgsrc/chat/jabberd2 # make extract # cd work/jabberd*/tools # su pgsql $ psql -U jabberd2 jabberd2 jabberd2=> \i db-setup.pgsql jabberd2=> \q $ exit # cd /usr/pkgsrc/chat/jabberd2 # make clean
We will use this database later in the configuration for jabberd2.
Before creating the databases themselves, you should create an PostgreSQL user with the same username as your unix username. Because PostgreSQL also identifies users by ther system user id. I recommend using the same user as you use for G System development. Then you should create two databases owned by that user, we will call them gclient and gserver. As usual, replace <username> with the actual username you intend to use.
# su pgsql $ createuser <username> $ createdb -O <username> gserver $ createdb -O <username> gclient $ exit #
The created user does not have any password set, which is fine because PostgreSQL only allows connections from localhost by default.
We will use these databases later for running the G Universe Server and the G Universe Client on localhost (this computer).
jabberd2 is an XMPP server. XMPP is the protocol used by the G World Engine for network communication. Look at http://www.xmpp.org and http://www.jabber.org for details.
Please note that there are probably better XMPP servers out there, especially fully XMPP compliant servers like ejabberd are preferred. So using jabberd2 is just one possibility - jabberd2 is also integrated in pkgsrc, so it's easier to set up.
For jabberd2 we need to slightly tweak the requirements for the rc scripts. In particular c2s and sm need as requirement the pgsql service, to make sure PostgreSQL is started before jabberd2.
To do so, add pgsql to the REQUIRE: settings of /etc/rc.d/c2s. The complete header will look like this:
#!/bin/sh # # $NetBSD: c2s.sh,v 1.2 2004/06/26 11:21:46 abs Exp $ # # PROVIDE: c2s # REQUIRE: DAEMON pgsql
This will make sure that PostgreSQL is started before the c2s component of jabberd2.
Finally we need to actually enable jabberd2 in the rc configuration. Add the following lines to /etc/rc.conf:
jabberd=YES c2s=YES sm=YES s2s=YES router=YES resolver=YES
For this to work you must have the appropriate rc scripts in /etc/rc.d/. Look at Packages to install to learn where you get the rc scripts from.
Configuration of the Jabber2 daemon is actually rather easy. The default configuration is just fine except that we need to use pgsql for authentication instead of mysql. This needs to be set in the c2s and sm configuration.
Go to the directory /usr/pkg/etc/jabberd/ and edit the file c2s.xml. Look for the section called Authentication/registration database configuration and within <authreg> set pgsql as the backend module to use. Do the same for the s2s.xml configuration file. The settings for the PostgreSQL database itself is already correct, as it uses the jabberd2 user and jabberd2 database name by default. The password has no effect as the jabberd2 user is not password protected.
Before you proceed it is probably a good idea at this point to reboot your machine and see if the whole startup procedure works fine, especially with regards to the PostgreSQL database and Jabberd2. Another reason is to make sure that the environment variables are all set when you log in as user. If you know your system well enough you'll certainly be able to achieve all this faster without rebooting, of course.
Getting the sources and compiling is explained in detail in the chapter Source Management. It is recommended to check out the sources into the $HOME/devel/G/trunk directory.
Please also make sure that you are able to compile all of the G System source code. You should be able to perform this step with ./scripts/compile from within the trunk directory of the sources. Please note that the 3.4 version of gcc will not work correctly, use a different version. NetBSD 3 uses gcc 3.3, so that works just fine.
And make sure that you do not install the G System into the system. That is, do not call ./scripts/makeinstall.
So far you cannot register a Jabber/XMPP account from within the G System applications. For this you need to use any of the available Jabber clients, like Kopete or Psi.
Make sure you register two accounts:
Accounts to register
G Universe Server account
server: localhost
Jabber ID: gserver@localhost
password: abc
G Universe Client account
server: localhost
Jabber ID: gclient@localhost
password: abc
Both the client and the server use an xml configuration file for network and database settings. After you have compiled the G System you can use ./bin/god to create and edit any of these configurations.
Put the server configuration into /usr/local/etc/gweconfig.xml and the client configuration into $HOME/.guniverseclient.xml.
Within the configurations, please replace gdev with the actual username that you use. For better clarity the desc attributes have been removed.
The content of /usr/local/etc/gweconfig.xml looks like this:
<gwe_controller value="advanced" > <db_driver value="QPSQL7" /> <db_host value="" /> <db_name value="gserver" /> <db_password value="" /> <db_port value="" /> <db_username value="gdev" /> <init_network value="yes" /> <master_server_jid value="" /> <xmpp_jid value="gserver@localhost" /> <xmpp_password value="abc" /> </gwe_controller>
The content of $HOME/.guniverseclient.xml looks like this:
<gwe_controller value="advanced" > <db_driver value="QPSQL7" /> <db_host value="" /> <db_name value="gclient" /> <db_password value="" /> <db_port value="" /> <db_username value="gdev" /> <init_network value="yes" /> <master_server_jid value="gserver@localhost" /> <xmpp_jid value="gclient@localhost" /> <xmpp_password value="abc" /> </gwe_controller>
We are now ready to run the G Universe Server and the G Universe Client on localhost, connected to the local PostgreSQL database and communicate through the local jabber/XMPP server.
First start the server: ./bin/guniverse and then the client: ./bin/guniverseclient.
If you have the docbook packages and libxslt installed, you can also build the documentation. To do so, run ./scripts/makedocs from the base directory of the G System sources. You can set various parametres for the script, depending on what you actually want to build, the output of running the script without parametres will tell you what options you have.
If you want to use KDevelop you can simply do so by running KDevelop and choosing Import Project... from the Project menu. Then select the $HOME/devel/G/trunk directory, set GSystem as project name and choose Qt C++ Application (QMake based) as project type.
You can make your life easier if you enable code completion, also for the Qt library. Go to Project settings and add Qt to code completion in the C++ settings. Note that KDevelop won't provide you with code completion for the x3dtoolkit, the qglviewer and the xmpp libraries, as these are included in the project files - KDevelop does not detect this.
When using KDevelop you should be aware of the following guidelines:
Do not edit qmake project files from within KDevelop
Never add or remove files from the project from within KDevelop, which implies changes to the qmake project files. If you have to change qmake project files after you have added or removed classes, close KDevelop, edit the project file and restart KDevelop.