Preface
The documentation for this project assumes that you have a basic knowledge of the functions of a GNU/Linux or Unix operating system. At the moment, it is not recommended for absolute beginners (those with very minimal knowledge of GNU/Linux or Unix). There are many resources available to help you, should trouble be encountered during the installation or further use of JD4X. See the
Getting Help section of the Documentation for further details. Lastly, due to the restricted size of our Development Team, the JD4X environment is not fully-tested on all Linux distributions or under all configurations. The popular RPM distributions (Red Hat, Mandrake, SuSE) should be fully compatible but nothing can be guaranteed.
Common Problems with Installation and no Solutions (Just Links to Them)
Java 2 Runtime Environment
Before beginning installation of the JD4X Desktop, it is imperative that you have Java 2 Runtime Environment (J2RE), version 1.4.0 or later installed and functioning properly on your system. The J2RE is included with the J2SDK, so if you have installed that package, and it works, then you are ready to go. Ensure that the J2RE can be started with the command java, or remember to substitute the proper command whenever java is used in the following instructions. If the Java 2 Runtime Environment is not proprerly install, or requires an update, please see The Official Java Web Site.
Scope of Installation
The next thing you need to consider is whether to install the environment for all users, or in a single user account. In order to install for all users of a system, you must be able to gain superuser access to your system. It is recommended to install for all users of the system, so you may need to request help from you System Administrator if you cannot become superuser by yourself.
Backing up Important Files
Many users are afraid of backing-up files. Many users find that their data is irretrievably lost forever. Should you think it is wise to back up your data, but are just too lazy to bother with everything, there are some recommended files that we think you should not install JD4X before creating copies of. These files are .xsession and .Xclients (or .Xsession and .xclients or however you find them). These files will be in your home directory (say, /home/cra if you are me). It is always a good idea to back up all your system files, but not even a perfect user such as myself can claim to do that. Also, nobody has ever lost their complete system to JD4X ... yet.
Unpack the Files and Move Them around
If you are installing system-wide (for all users) then the first thing you need to do is become superuser. See our section on <Being Superuser> for more information. Once you are <in the directory where the jarfile is located>, you can unpack the files with the command following command:
java -jar install.jar
This command will start a GUI interface which allows you to select the output directory for the environment's files to be uncompressed into. If you are superuser, and want to install JD4X globally (which is recommended) then you should probably choose a subdirectory of /usr. Otherwise, you will need to choose a directory where you have writing permission, probably a subdirectory of /home.
Has it Been Copied Correctly?
You now need to determine whether or not the files were successfully copied to the location you specified. To do this, use the following commands (where /usr/local/jd4x is replaced with the directory you installed into):
cd /usr/local/jd4x
ls
At this, your computer should output a list of the files in the directory. If the list is blank, then something has gone wrong and you should contact us with the error messages from the Virtual Machine.
Check for .Xsession and .Xclients (Skip This if You Backed Up These Files)
You are going to run into serious problems during the following installation of the standard .Xsession and .Xclients scripts you were supposed to have backed up already either do not exist, or are not in the standard format. So if you have not yet backed up these files, it is now time to do so. Exit your superuser session, and change directories to your home directory (cd alone, with no argument). Now use the cp command (format: cp fileName copyDirectory) to copy the files .Xsession and .Xclients to another directory which you will remember. If the file cannot be found, try changing the uppercase X to a lowercase x. If this still does not work, then installation is not yet supported on your machine; thank you for trying JD4X and we hope you have a great time with your old desktop manager.
Installation for a User
If you are currently running a shell window as superuser, you should exit as this is no longer necessary (though keep the shell window open - implying that if you do not have one, you need it). It is advisable that you are now installing as a user with no saved settings (that way if JD4X makes the plasmabeam in your harddisc malfunction and cause post-pranial upper-abdominal distention, you are prepared).
You now need to execute the setup program again, and it is easiest to do from inside the directory where it is installed (use cd directoryWhereSetupProgramIsLocated). Then execute the following, which will start the correct installation process:
java -jar install.jar
Another nifty GUI (Graphical User Interface - essentially, not-on-commandline) installer will be started at this point, and guide you through the rest of the installation.
Errors During Installation
Operating System Error: this means that JD4X has not yet been ported to your Operating System (OS). If you can help us do this, please let us know.
Vendor Error: this means that you have not properly installed the Java 2 Runtime Environment (J2RE) version 1.4.0 or higher. It also means that you are a fool, because you should have checked this in the section called "Java 2 Runtime Environment". Scroll up and read it now.
X Window System Error: this means that you are currently using the default desktop system indicated in your .Xclients script (assuming you followed the second-previous section). You will need to use a different desktop system in order to complete the installation (as it is impossible to edit this file while you are using it).
Configuration Warning: Although not technically an error, this warns you of possible problems due to a previously-installed version of JD4X. If you want the default menu to include all third-party software added under the previous configuration, you must agree to having the old configuration file removed. If you choose to keep the previous configuration file, and are installing JD4X in a different location than the past version, you may experience errors later on regarding the locating of critical files. Just a warning. Perhaps you should have backed this up?
(Continued) Installation for a User
If you do not know what further options mean during the GUI (Graphical User Interface) installation, then keep them at their default values and simply continue installation. Upon completion of installation, you simply need to log out and re-login. Assuming everything works as planned, you should be enjoying a brand new JD4X desktop.
If It Does not Work Correctly
If, upon logging out and back in again, your desktop does not correctly start up, it is possible that you need to select JD4X from the option menu on your login screen. To do this, you will need to log out again, and select "Default", or "Default Desktop" or something similar to this. If you modified the scripts for startup, then choose an appropriate option other than Default.