Here you can find some tutorials and short howtos.
Some of these are for a broader mass but some also for internal information. If you have any questions, feel free to ask, either via e-mail or in our forums.
Here you can find resources about topics related to cross-platform issues.
Ever been frustrated about spending a lot (certainly too much) time on compiling your apps for all the platforms you seek to support? Don't want to repeatedly reboot your machine to start one for one the operating systems to compile your program there? Well, if you use to write your applications in (Free) Pascal, your happy ;-)
What is cross compiling?
Cross compiling means, that you compile a program for a platform from another one. For example: If you work on Linux, you can compile your project also for Windows operating system. Sounds interesting? It is! However, it does not work "out of the box". First we have to work a little bit and set up our cross compile environment.
Windows users: Watch out!
If you think, that you can provide your apps now also for Linux and other systems I have to warn you. It is possible to compile Linux and other UNIX-oide apps using windows. But you will need a lot of stuff for this way round! As static linking is hard enough, dynamic linking will certainly drive you mad, if you don't are ready to spend a lot of time - especially for learning the backgrounds. Same thing for Linux users who want to compile e.g. for OpenSolaris, FreeBSD, ...
Instead of providing binaries for each UNIXoid operating system, consider writing good Makefiles. That will probably make your users more happy.
Lets begin!
So, what will this tutorial tell you? First of all: I will assume that we are on a 64bit Linux operating system. You probably can substitute "Linux" by any other UNIX-like operating system, as long as it is supported by Free Pascal. Second: I will also assume, that you want to compile your apps for Linux (64bit, 32bit) and Windows (64bit, 32bit). Again be warned: It is complicated to cross compile e.g. from Linux to FreeBSD. I will not cover this here - however you can try it yourself.
Step 1: "Building" cross linker and assembler
As we are on a 64bit Linux, we need linker and assembler to be able to generate their stuff for 32bit. This is possible. And it is easy to realize for us. First, check whether you already have these binaries:
Step 2: Downloading Free Pascal
Now you'll need to download the Free Pascal source tarball of your choice. It doesn't matter whether you use stable versions or checkout from SVN repos. You will also need a 64bit and a 32bit version of the Free Pascal compiler (if you don't already have them). Let's assume your machine is a Pascal-free zone and you also downloaded the pre-compiled Free Pascal binaries for Linux 32bit and 64bit additional to the latest stable source tarball.
Step 3: Installing Free Pascal in your home folder
Now we'll install the two binary packages at home. Why? Well: I don't like to mess up my system more than needed. We will be able to compile our own compilers later, and let "make" do the job of installing.
So, un-tar the two packages and run the contained install script:
Step 4: Compiling Free Pascal for Linux 64bit and 32bit
Now we can compile our own compilers for 32 and 64 bit. Simply unpack the source tarball and fire up make:
Step 5: Compiling the compiler, RTL and packages for Win32
Next step we will create a Win32 compiler and - what is much more important - the RTL and packages for Windows 32bit operating systems. This is as easy the the above step, as we just need to adjust the parameters for make:
Step 6: Compiling Win64 RTL and packages
OK, now we nearly have it done. The last step is to add support to compile to Windows 64bit systems. This is also easy to solve, despite it differs slightly from the steps we did for Win32:
Step 7: Cleaning up
Before starting to use your cross compilation environment, you should clean up. Remove the local installation of Free Pascal in your home folder and also don't forget do edit your .bashrc file: Remove the path references to the removed installations in your home directory and add the path where FPC is installed ("/usr/local/lib/fpc/$FPCVERSION").
Step 8: Creating a configuration file
The last step is to create a configuration file for Free Pascal. To ease this, there is a script in the compiler's directory:
Conclusion
Well, done! You now have a fully working cross compile environment which allows you to compile for Linux and Windows (each 32 and 64bit). You don't believe it? Then try it out! Create a pascal source file "hello.pas":
At last, a few notes:
When upgrading to a newer version of Free Pascal, you don't need to download the pre-compiled packages, again, as you then already have a compiler for each 32 and 64 bit.
You should also note, that the compiled units and object files (*.ppu, *.o) are not compatible among compilers and target platforms. That means: If you have a collection of Pascal source files and want to pre-compile them, you have to put them into different locations. If you have a closer look at the Free Pascal configuration file, you'll notice, that there two place holders are used: $fpcversion and $fpctarget.
The second will be replaced by the target platform you compile to, and is of the form ARCHITECTURE-OPERATINGSYSTEM. So, if compiling e.g. to Win32 fpctarget will be replaced with "i386-win32". The first - fpcversion - will be replaced by the version number of the Free Pascal compiler that is used.
That was it! Your system is now fully set up (at least for the basics). Working on only one platform and compiling to all the platforms you want to support has a lot of advantages: You only need to set up one system as a development system (in dual-boot environments), don't need to use "tricks" (as installing Free Pascal inside a Wine environment) and you are able to write scripts to automate the compilation and packaging process.
This section contains tutorials that describe how to install and setup some software packages.
This tutorial has been written mainly as a result of some trouble we had in our practise at TUD when we had to set up Apache Tomcat for the project. It describes how to install and set up the Java Development Kit, Apache Tomcat and Eclipse.
Table of Contents
Apache Tomcat needs the Java Developent Environment installed on your machine. Depending on the Tomcat version you plan to use, you maybe need different versions of the JDK. The newest version of Tomcat (6.0) needs the JDK 1.6. You can download the JDK 6 e.g. from here.
Note:
Do not mix up the Java Runtime Environment (JRE) and the Java Development Kit (JDK)! Tomcat will need the latter! You do not need to download the JRE separately, as it is included in the JDK.
Afterwards, you are advised to create a new environment variable JAVA_HOME that points to the directory where you installed the JDK (on Windows this is mostly C:\program files\Java\jdk-x\. Also add the path to the JDK's "bin" directory to your PATH environment variable!
To check whether you setup everything correctly, open a terminal window and type
Next, you can download Apache Tomcat. Go to their Website and download your preferred version of Tomcat. The current version of 6.0, which needs the JDK 6 we just installed. If you download an older version, you will probably need also an older version of Java installed!
Do download the zip or tar.gz version and unpack it. Then, enter the directory and go to the conf directory. There you'll find several xml files, where Tomcat's settings are stored. The default settings are pretty good, however, you can change them if needed (e.g. you might prefer to change Tomcats default port to 80 instead of 8080).
Eclipse is a pretty cool IDE that really supports a developer. Thus, it also enables you to run a web application directly in the IDE!
But first:
Go to the Eclipse Download page and download Eclipse for Java Developers. Select your operating system there and you'll end up with an archive file you just have to unpack to an location of your choice. Enter the eclipse directory and start the executable you'll find there.
Create or import a Web application. Then you can start it via Run as and start it on a server. Then you should see a window where you will find a list that also contains several versions of Tomcat. Select a version there. Then you will also have to set the path where Tomcat is installed. Afterwards, simply click Finish and Eclipse should start the web application directly in the IDE.
If you have included a 3rd Party Java Library in your Eclipse project you maybe already noticed, that you don't get that neat and sometimes really useful context help when hovering e.g. a class name from that archive. However, it is possible to add this feature for the archive, too.
After you added the Jar to your project, it should be visible in Java Resources ยป Libraries. There, right click it and select Properties.
Now, go to Javadoc Location. You will end up in a new tab, where you can set up the Javadoc location for that Jar. You currently can select to either give an URL to a valid Javadoc location (you can enter both online and offline paths here, e.g. http:// or file:/), or to specify an archive file containing the documentation.
After you finished, hit Apply and enjoy programming ;)
The Project Explorer integrated in Eclipse IDE is a really nice feature. However, when working with a lot with packages, you may need to tweak it a bit...
By default, the explorer shows packages in a flat view. This is because some projects use to use names as org.eclipse.XXX and so on. For these a flat view is quit perfect.
However, if you use packages to structure your own projects hierarchical, you might want to have a tree view like display, as it heavily shortens the length of the list of items that are displayed at once.
To change the display mode, click onto the little arrow-down symbol in the Project Explorer (should be in it's titlebar on the right side). There, go to Package Presentation. Now you can select between the flat and the structured ("Hierarchical") view modes.
Usually, you log in via SSH using your remote user name and password. However, you does not need necessarily.
You can also log in by using a so called fingerprint. So, don't let us wast a lot time; here is what you need to do:
First, generate a local key pair:
Now we are really close: Log in on the remote server and add the fingerprint to the list of authorized keys:
That's it! If you try to connect to the remote server the next time, you will no longer need to provide your password.
A lot of keyboards today come with a bunch of multimedia keys. On laptops on the other side you often have a Fn key used to activate a further function of a given key. The xbindkeys tool gives you the possibility to bind these keys to your preferred actions!
First, you probably have to install the xbindkeys utility, as it isn't installed by default as far as I know. However, it should be included in most distros repositories, so you can just use your distribution specific tool to install it, e.g. in Fedora type:
Next, you should create a personal configuration file. The xbindkeys command can create a default one for you, too:
OK. Now open the newly created file with your editor of choice. The file has a pretty easy to understand syntax:
Next, we have to find out the key codes. E.g. on a usual laptop, the key combinations Fn + F11 and Fn + F12 are used to decrease/increase volume. To bind these two events to an action, we use xbindkeys to figure out their codes:
Now, a small window should pop up. You can now press some key combinations (also with Ctrl, Alt and Meta modifiers). In my case, I use Fn + F11 and (in the second iteration) Fn + F12, which results in these output:
Now we can insert the key codes together with the actions in the configuration file, by just appending this to it:
Now... a last step to do:
We have to start xbindkeys daemon! This can be done by simply calling:
From now on, pressing Fn+F11 or Fn+F12 should change your volume! To autostart the xbindkeys daemon, you should put a script in your personal autostart folder (e.g. $HOME/.kde/env/ when you use KDE or $HOME/.config/autostart/.) The script can look like this:
That's it! Have a lot of fun!
Tutorials about version control systems.
Version control systems (VCS) have become an integral part of the software portfolio of each developer - no matter whether commercial or free software. This article shall present some ideas and explain the most important vocabulary.
Table of Contents
Well. Yes. At least it is a wise decision to use one.
First, VCS systems help to keep a backup copy of your project, especially those systems that use a central place to store their data. Every 30 seconds* a project goes forever just because a hard disk died or the owner lost the USB stick with the last existing copy of the software's sources.
But this is surely not the only reason:
When having only the most recent copy of a project's sources, it is generally difficult to say, when a bug or unwanted feature entered. If you can just look back into the sources of last week, when everything was fine, it is much easier to find out.
Last but not least: What about different versions of a software? Usually, even in small projects there exist two kinds of the software:
A development version, where all recent changes go to and which tends to be somehow unstable. And versions that are pretty stable ("releases").
Now you can say: What's the problem? Just make a copy of the sources and store it somewhere before starting development again.
That is true, if you can say for sure, that you will not alter the released versions. But what if an ugly bug is found?
VCS help you with all these points. However - as with every support software you can use - you usually have to learn the software and some vocabulary around it. And this is what this article is intended for, too.
The following terms and phrases tend to cross your way in VCS-related things, so it is a good idea to know what they mean:
The repository is the place, where a VCS saves the project and its past. That means:
You can get the latest version of the software from a repository, but also every state it was in in the past. A "state" is usually called a revision, and VCS tend to mark them e.g. with a alphanumeric key, to identify it. The latest revision is usually called HEAD.
There are two different ways VCS tend to tread their repositories:
There is only one central repository, everyone has to interact with.
There are several copies of the repository around. Usually, when getting a copy out of the repository, the complete repository is copied and later they only synchronize.
This combines the above two ways: Generally, these systems work distributed. But there is also a central repository where the software is "officially" kept.
The act of getting a copy of the software if mostly called checkout. This usually gets you the latest version of the software, but when you wish, you often can also get an older revision. Beneath, a checkout usually also copies some meta information, that is used when you update your copy, revert changes or if you want to give your changes to the software back, which is called a commit or checkin.
When using distributed systems, there is mostly nothing like a checkout. Instead, you clone the complete repository and then can access all revisions of the software from your local copy.
VCS are essential when multiple developers work together on the same software and even on the same set of source files. In such cases, wanting to manage the software yourself will soon be painful.
VCS have usually two different ways to allow collaboration, sometimes these can be mixed or used on the developers flavors:
In this case, when a developer starts developing on a given set of files, he locks them. All other developers are then disallowed to write the files in the repository. This way has the drawback, that there is no full collaboration. When there are files all developers often have to alter, this mechanism can be painful. However, it's clear advantage: There will never be conflicts! As soon as a developer starts developing, he locks the central system. When he commits back his changes, the files will not be altered and can simply be overridden. This does not make sure, the software will still compile (e.g. when he removed a method from a class, and this method is still used in a class of another developer, compilation will fail).
This allows true collaboration, even upon the same files: A developer just checks the current copy of the software out, alters the sources and then commits them, hoping the files in the repository have not changed too much, so that the VCS will be able to merge his changes automatically back into the repository.
The drawback here is, that there can be conflicts: If the files in the repository changed too much in the meanwhile, the VCS will not be able to merge the changes back. In such a case, the developer has to review his changes and eventually update to a newer version of the software.
Usually, a software has a development copy, where main development takes place. This is usually called trunk or master.
Beneath, there can be so called branches. A branch can be developed apart from the progress in trunk. Usually they can be used if a new version line of a software begins (0.0.x, 0.1.x, 0.2.x and so forth):
While the trunk is then actively developed, important patches are also applied to the highest of these branches. This is because the trunk is usually pretty unstable, however, especially security patches must be applied to the currently released version of the software too!
Beneath, branches can also be used to develop two totally different versions of the software: Imagine your software used to use library X for PDF output but you want to change to library Y. Here, it is a good idea to create a new branch first and make the changes there. If Y proved to be reliable enough, you can merge the branches so that you again only have one.
Branches, as already said, are used to develop different versions of the same software. Beneath, there are also so called tags used. A tag is rather static: You usually use it to mark a special revision of the software, e.g. a released version (0.4.2, 1.3.37, 1.0.24 and so on).
Tags are not developed further. Indeed, you can just refer to the key the VCS use to identify a certain revision. But as tags tend to be more human-readable, they are used nevertheless.
Version Control Systems alone are pretty useful and important for software development. However, especially people who are unfamiliar with them tend to ask, whether they can "destroy" something per accident. Well. They can indeed cause some additional and especially redundant work. However, really destroying the structure of a repository is uneasy so don't be worried.
However, one thing can happen of course, and not only to newcomers:
That one checks in rubbish or forgets to commit an integral part. What will be the matter? On his machine, everything will be smooth: He will still be able to compile the software and everything's fine. But the next person to checkout the HEAD will probably not be happy. Going further: Is there any way to prevent this? Well... not really. Human tend to fail, and will always do so. However, there is software out there to bring the repository back to a usable state as soon as possible: So called Continuous Integration Software. This software listens on the repository. As soon as someone commits, it starts compilation and build processes. If these fail, the developer will get a warning, e.g. by e-mail. This way, he knows that something went wrong and he was somehow a part of the failure (if he caused it, is another question, e.g. when the error is connected to a function that has been removed on the commit just before). Easy spoken, the concept is pretty equal to: Before committing, update to HEAD, try to compile and if - and only if! - compilation went smooth, commit. However: Who can say that there will not be a commit between end of compilation and the commit? Correct: Nobody!
Continuous Integration software automates this process and lets you know there were problems as soon as possible, reducing damage to a minimum.
[*] To be honest: This number is probably inaccurate. I haven't ever seen a statistic about this topic. However: Be warned. Loosing data is much easier than finding it again or restoring it from broken devices!
Git is a distributed version control system. It allows development distributed over several machines, but also knows central repositories.
Table of Contents
Git is a version control system, or VCS for short. Like SVN and CVS, it allows you to manage your projects and keep track of their history. This is important, as you often need to return to a earlier state of your software (e.g. when latest modifications are error prone or unneeded or ...)
In contrary to SVN, which knows nothing about "branches" or "tags", these things are built-in into Git. Git provides easy to use commands to create and manage these.
Git is - not as CVS and SVN - centralized but distributed. That means:
Every developer who checks out a repository, indeed copies the complete repository including its history to his computer. He than can develop as usual: Revert changes, manage branches and tags and even commit changes into his repository. Later, when he is ready (or has again a connection to the internet, which he had not e.g. when he traveled by train) he pushes his changes back to a central repository.
So you want to start developing and contributing to a project, let's say RPProject, which uses Git and has a central repository on Gitorious. First thing is to get a copy of the current repository:
This will get you the current repository and needed meta data. Note, that you now have a complete repository, where you already can make changes, even if you don't have write permission to the central repository.
If you cloned the repository before, you maybe just want to get the newest changes from the central repository. To do so, change to the directory you cloned and there:
First, change to the master branch. This is, where stable commits should go. If you cloned a fresh repository, you usually only have the master branch. The second line fetches all updates that are waiting in the remote repository.
Now you can start developing. It is usually a good idea to create a own branch you only see in your local repository:
Line 1 creates a new branch called devel. The second line switches to the new branch.
If you updated the master branch to reflect the changes in the remote repository, you might wish to apply these changes to your development branch as well:
First make sure you are in the development branch, and then, in line 2, merge the changes in master into the development branch.
Now, just start coding!
If you add new files or need to remove unused ones, do:
If you are ready to commit your changes, first check the current status:
This will list:
If you added and removed all files, you can commit them into the local repository:
If you just modified existing files, you do not necessarily add them via git add. Instead, use:
If your changes are ready for seeing the rest of the world, first bring your master branch up to date:
This will merge the changes you made in the development branch back into master.
Now, you can push your changes to the central repository: