Cloxten - The Clock Extension Tool ------------------------------------ Version 0.1.7 Copyright 2002-2003 Alberto Lohmann This file is free software; as a special exception the author gives unlimited permission to copy and/or distribute it, with or without modifications, as long as this notice is preserved. This file is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY, to the extent permitted by law; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. ------------------------------------ This file can help you in the following topics: 1. Project Summary; 2. About project; 3. About version; 4. Cloxten binaries and source code 4.1. Disclaimer; 4.2. How to get Cloxten; 4.2.1. Cloxten pages; 4.2.2. CVS 4.2.3. APT-GET (Debian only); 5. Riquired libraries; 5.1. Info; 5.2. How to get libraries; 6. Untaring packages (If you are new in Unix systems); 7. Build Cloxten binaries (if you got the source package only) 8. Setup: 8.1. Install and/or uninstall Cloxten files; 8.1.1. TAR.GZ Installation; 8.1.2. RPM Installation; 8.1.3. DEBIAN Installation; 8.1.4. TAR.GZ Uninstallation; 8.1.5. RPM Uninstallation; 8.1.6. DEBIAN Uninstallation; 8.2. Install and/or uninstall required libraries; 8.2.1. Install required libraries; 8.2.2. Uninstall required libraries; 8.3. Required libraries post-install; 9. Running Cloxten; 9.1. Playing audio files; 9.2. Sending mails ("Remote notes"); 9.3. Internet settings; 9.4. How to get help; 10. Contact author. ------------------------------------ 1. Project Summary: ================== * Development Status: 2 - Pre-Alpha * Environment: X11 Applications * Intended Audience: End Users/Desktop * License: GNU General Public License (GPL) * Natural Language: English * Operating System: GNU/Linux * Programming Language: Delphi/Kylix * Topic: Office/Business ------------------------------------ 2. About project: ================ Cloxten is a digital alarm clock and counter. It is able to execute a variety of events and actions at set times, such as send messages, sound signs, play a music file, open a file or execute a program. Cloxten runs on GNU/Linux. As project is under development and current status is pre-alpha, it was not tested enouth. Use it at your own risk. CLOXTEN IS LICENSED FREE OF CHARGE. ------------------------------------ 3. About version: ================ Current version is 0.1.7 Pre-Alpha. Wizard form is fully implemented, including help texts, integration with the rest of the code, as well as, some features were added such as the status panel, with simple texts at this moment, and the option to skip copyright notice, for older users. All "translatables" strings of Cloxten binary (not Doctor Doc yet) were placed in a single file (cloxten/strings/strings.pas). I think it's not the right time to start translations into another languages, because there are some features I want to write. And besides, Doctor Doc and its helpful texts have no 'strings.pas' yet. As usually some minor bugs were fixed too. Please, see ChangeLog, that comes with distribution, for a complete changes view and features added. Cloxten's already a good choice, but if your interest is in a stable version, or close to that, visit regularly the following pages: http://cloxten.sourceforge.net http://sourceforge.net/projects/cloxten ------------------------------------ 4. Cloxten binaries and source code: =================================== 4.1. Disclaimer: =============== This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See COPYING file for details. 4.2. How to get Cloxten: ======================= Please, see "Required libraries" topic in this README file to know if you need them. 4.2.1) Both source code and binaries are placed into packages for download in: Cloxten home page http://cloxten.sourceforge.net or in Cloxten project page http://sourceforge.net/projects/cloxten 4.2.2) CVS: The project CVS repository can be checked out through anonymous access. Instruction can be found in: http://cloxten.sourceforge.net/download/cvs.html or http://sourceforge.net/cvs/?group_id=49083 4.2.3) APT-GET: Latest Debian Woody repository for Cloxten binaries: (maybe works with unstable too) Add following line to your apt sources.list. deb http://cloxten.sourceforge.net/apt/cloxten/latest/Debian/woody ./ ------------------------------------ 5. Required libraries: ===================== 5.1. Info: ========= Cloxten needs: * libqt.so.2 (the Qt library) * libqtintf-6.5-qt2.3.so (the Qt interface library) These files are NOT copyrighted by Cloxten project. They are third-party softwares. You can use them under certain conditions, that will be showed to you at download time. If you use KDE 2, you probably don't need libqt.so.2 (the Qt library). 5.2. How to get libraries: ========================= The Qt library and Qt interface library: 1) Binary: http://cloxten.sourceforge.net/download/libs.html 2) Source: * The Qt library source: Version 2.3.0: ftp://ftp.trolltech.com/qt/source/qt-x11-2.3.0.tar.gz All versions: ftp://ftp.trolltech.com/qt/source/ * The Qt interface library source: Kylix distribution doesn't come with a 'Runtime Library Makefile' for Qt Library Interface. However, there is an open source project named FreeCLX related with it at http://sourceforge.net/projects/freeclx Unfortunately, it's not updated for a long time. Cloxten was tested with latest FreeCLX release (2.2.4.4), but fails to be executed. So, it's recommended to use the pre-compiled library found in Cloxten download page. ------------------------------------ 6. Untaring packages: ==================== (If you are new in Unix systems) Next lines, I'll show you how to unpack Cloxten files. For installation, see "Setup" topic in this README. For this example, version 0.1.7-1.pa is used, but it'll work with any other. Simply change your work directory to where you downloaded Cloxten file(s). $cd [where I placed my files] See if files are in. $ls -l cloxten* cloxten-0.1.7-1.pa.src.tar.gz cloxten-0.1.7-1.pa.tar.gz NOTE: You don't need both 'cloxten-0.1.7-1.pa.tar.gz' (binary dist.) and 'cloxten-0.1.7-1.pa.src.tar.gz' (source dist.), just one of them. Choose the appropriated one. Now unpack files $tar -xzvf cloxten-0.1.7-1.pa.tar.gz [... tar's verbose output ...] or use $tar -xzf cloxten-0.1.7-1.pa.tar.gz IMPORTANT: Cloxten packages were compressed with gzip option. Run tar with the '-z' argument as shown. Repeat it for wich package (if you need them). After that, see "Setup" topic. For source distribution, see next topic (7. Build Cloxten binaries) before Setup. ------------------------------------ 7. Build Cloxten binaries: ========================= (if you got the source package only) If you are an end user and just want to execute Cloxten, you may skip this topic and get a pre-compiled package. The Kylix packages in Cloxten's page are runtime libraries used to execute a pre-compiled Cloxten binary (or any other program built with Kylix). They can NOT be used to build Cloxten binaries. First, I'll assume that you have the Kylix (http://www.borland.com/kylix) compiler and know how to use it. The simplest way to build cloxten is: 1st) Initialize Kylix "vars and args": $source [MY_KYLIX_HOME_DIR]/bin/kylixpath [MY_KYLIX_HOME_DIR] >/dev/null 2nd) Building 'cloxten.bin' (Required): $cd [where I untared Cloxten source]/cloxten-[VERSION]/cloxten $[MY_KYLIX_HOME_DIR]/bin/dcc cloxten.dpr $ls cloxten.bin cloxten.bin 3rd) Building 'doctordoc' (The help program - Useful but optional): $cd [where I untared Cloxten source]/cloxten-[VERSION]/drdoc $[MY_KYLIX_HOME_DIR]/bin/dcc doctordoc.dpr $ls doctordoc doctordoc --- Optionally, you can edit and use the 'build' shell script in 'bin' directory that do this work. ------------------------------------ 8. Setup: ======== 8.1. Install and/or uninstall Cloxten files: =========================================== Before execute Cloxten, You should install the required libraries in a directory that is listed in the LD_LIBRARY_PATH environment variable, or listed in the /etc/ld.so.conf file. Otherwise, Cloxten will fail to be executed. See topic '8.2'. 8.1.1) TAR.GZ Installation: From version 0.1.5, Cloxten uses Loki Setup Installer to install its files. You don't need it if you are planning to use RPM and Debian packages. To use this installation method, first you need to read the file 'bin/SETUP/README'. IF YOU SKIP THIS READING, SETUP WILL FAIL. After that, follow with these instructions: Open a terminal emulator and execute the shell script named 'setup.sh'. $su (if you don't need special system access, skip this line). #cd [where I untared Cloxten distribution] #./bin/setup.sh Follow the installer's instructions. If nothing goes wrong, that's all. 8.1.2) RPM Installation: From version (0.1.3), you have the opition to install Cloxten with 'rpm'. If you downloaded one of the rpm packages, use your predilect RPM Installer or in a terminal type: $su (if you don't need special system access, skip this line). #cd [where I downloaded Cloxten RPM file] #rpm -ivh cloxten-[version].rpm Preparing... ########################################### [100%] 1:cloxten ########################################### [100%] #exit $ 8.1.3) DEBIAN Installation: From version (0.1.5), you have the opition to install Cloxten with 'dpkg'. If you downloaded the DEBIAN package, use your predilect DEBIAN Installer or in a terminal type: $su (if you don't need special system access, skip this line). #cd [where I downloaded Cloxten DEBIAN file] #dpkg --install cloxten_[version]_i386.deb (Reading database ... ????? files and directories currently installed.) Unpacking cloxten (from ./cloxten_[version]_i386.deb) ... Setting up cloxten ([version]) ... #exit $ 8.1.4) TAR.GZ Uninstallation: Open a terminal emulator in the directory you installed Cloxten. Execute the shell script named 'uninstall.sh'. $su (if you don't need special system access, skip this line). #cd [where I Install Cloxten] #./uninstall.sh If nothing goes wrong, that's all. 8.1.5) RPM Uninstallation: $su (if you don't need special system access, skip this line). #rpm -ev cloxten #exit $ 8.1.6) DEBIAN Uninstallation: $su (if you don't need special system access, skip this line). #dpkg -r cloxten (Reading database ... ????? files and directories currently installed.) Removing cloxten ... #exit $ 8.2. Install and/or uninstall required libraries: ================================================ THIS TOPIC DESCRIBE TARGZ'ED FILES INSTALLATION AND UNINSTALLATION. FOR RPM AND DEBIAN, SEE TOPICS: Installation: '8.1.2' AND '8.1.3', respectively; Uninstallation: '8.1.5' and '8.1.6', respectively; CHANGING THE NAMES OF PACKAGES. TAR.GZ files: ============ You should install the required libraries in a directory that is listed in the LD_LIBRARY_PATH environment variable, or listed in the /etc/ld.so.conf file. You can also install libraries in any point of root tree, if you make symlinks to them in a directory that satisfy the above condition. 8.2.1) Install required libraries: You have two installation methods: 1st method) With Loki Setup installer: ============================================= To use this installation method, first you need to read the file 'bin/SETUP/README'. IF YOU SKIP THIS READING, SETUP WILL FAIL. After that, follow with these instructions: Open a terminal emulator and execute the shell script named 'setup.sh'. $su (if you don't need special system access, skip this line). #cd [where I untared required libs] #./bin/setup.sh Follow the installer's instructions. Some possible values for 'link path' are: /usr/lib /usr/local/lib /usr/lib/qt2/lib (in many RPM systems) ... See /etc/ld.so.conf file for a list or type "echo $LD_LIBRARY_PATH" to know if your system has a default directory. If nothing goes wrong, that's all. 2nd method) Without Loki Setup installer: ================================================ Simply copy files in 'lib' directory to a directory that is listed in the LD_LIBRARY_PATH environment variable, or listed in the /etc/ld.so.conf file. WARNING: This method does not generate an uninstall script. To remove files from system, you'll need to do it by hand. 8.2.2) Uninstall required libraries: (If you installed files with Loki Setup). Open a terminal emulator in the directory you installed Cloxten required libraries. Execute the shell script named 'uninstall.sh'. $su (if you don't need special system access, skip this line). #cd [where I Install Cloxten required libraries] #./uninstall.sh If nothing goes wrong, that's all. 8.3. Required libraries post-install: ==================================== If you install the required libraries in a directory under your '/etc/ld.so.conf', but when you try to run Cloxten you get an error message like: cloxten.bin: relocation error: cloxten.bin: undefined symbol: initPAnsiStrings So, you need to update the 'ld.so.cache' with '/sbin/ldconfig'. Simply run '/sbin/ldconfig' as root (only once) and try again. ------------------------------------ 9. Running Cloxten: ================== It's recommended that you run Cloxten by its script (cloxten). If you install Cloxten in a directory not in your PATH, you'll need to edit this script. If Cloxten found no 'config dir', the Wizard Form will be shown. It's higher recommended that new users let it lead them. If you installed 'doctordoc', press F1 or click on 'Help' button to get online help. It detects active window and shows you the appropriated help text. 9.1. Playing audio files: ======================== You must enter at least one music player in 'Settings -> Payhs' tab, in Control Window to enable this function. Supported audio types are: mp3, oggvorbis and wave. Midi files can also be played if your wave player can do it so. You are free to choose which programs you want to use. As a reference, Cloxten was tested with the following binaries: MPEG Player: 1) mplayer; http://www.mplayerhq.hu/homepage/dload.html 2) mpg123. http://www.mpg123.de/ OGG Player: 1) mplayer; http://www.mplayerhq.hu/homepage/dload.html 2) ogg123 (*); http://www.vorbis.com/ 3) play (**). http://sox.sourceforge.net/ WAVE Player: 1) mplayer; http://www.mplayerhq.hu/homepage/dload.html 2) play (**). http://sox.sourceforge.net/ (*) A delay time was detected when trying to stop OggVorbis files using ogg123 player. (**) Current Cloxten version just play and stop audio files, it can not control them. To stop a sound execution, the program sends a kill signal to target 'pid'. As 'play' program is usally a shell script that calls another binary to execute the work, 'kill' will not work. If you decide to use this file, Cloxten will launch it but without the ability to stop it before the end of file execution. 9.2. Sending mails ("Remote notes"): =================================== THIS FUNCTION DEPENDS ON MAIL SYSTEM CONFIGARATION. IT HAS NO SUPPORT FOR REMOTE AUTENTICATION. IF YOUR SMTP SERVER REQUIRES IT, YOU MAY NOT SEND MESSAGES OVER YOUR LAN. IF YOUR NETWORK USES LOCAL MAIL AGENTS TO TRANSFER LOCAL MESSAGES OR YOU HAVE DIRECT ACCESS TO MAIL BOXES, YOU PROBABLY WILL NOT EXPERIMENT TROBLES. It was designed to let you send eletronic mails on your local area network (LAN) as if they were "notes" written to yourself or others. Doing so, "notes" can be read on any network machine. For this function, it's necessary to enable a mail check program (Cloxten doesn't do it yet). You may not have problens sending messages in your LAN, but if you want others networks (like internet) to accept your mails, you must have a smtp server configured and running. Keep in mind Cloxten isn't a mail cliente. As it was written to access your LAN, Cloxten use your local variables to compose messages. In case you want to change your sender email, and have root access to your system, configure the smtp server (sendmail, postfix etc) to mask it. There's no sense (I can see no one) to send a regular mail message by this method. Expecially because sent mails aren't save in any place. Email will be cached until user compose a new one or while 'Send a message' option in Control Window is active. However, you are free to do so. To enable this function, you must enter both a mail user agent and a text formatter in 'Settings -> Paths' tab in Control Window. As a reference, Cloxten was tested with the following binaries: Mail User Agent 1) mail; Standard mail program. Should be installed as default. 2) mutt http://www.mutt.org/ Text Formatter 1) fmt (fmt is part of gnu textutils) http://www.gnu.org/software/textutils/textutils.html or http://www.gnu.org/directory/textutils.html 9.3. Internet settings: ====================== From version 0.1.5, you can check for Cloxten updates and visit on-line project pages. For the first function you need the Gnu Wget installed and for the other one, an internet browser of your choice. As a reference Cloxten was tested with: 1) mozilla; http://www.mozilla.org/ 2) netscape; http://www.netscape.com/ 3) konqueror. http://www.konqueror.org/ Others fuctionallities are keeping in mind, as well. 9.4. How to get help: ==================== If you follow carefully all instructions in this README file but something goes wrong or if you installed the program successly and are esperimenting trobles that online help can't solve, go to Cloxten summary page at http://sourceforge.net/projects/cloxten on "Public Areas", open a support request for the version you are using. As the program is under development it's a good idea to always work with the latest one. PLEASE, tell all pertinent information. Do not write "Something's wrong, nothing happens..." or close to that. Don't expect I close your request in few hours. I work in this project during my free time. ------------------------------------ 10. Contact author: ================== "Alberto Lohmann" (Mails can be posted in English or Portuguese).