NanoGTK public release 1.0pre1 ============================== This release consists of a complete environment for developing and running GTK+ applications in Nano-X on top of X Windows. You do not need X11 version of Microwindows, GLIB and GTK+ installed on your PC. Nevertheness, you must have X Windows working on your PC. If you have your own applications and want to run them in NanoGTK, these applications should be compiled with the NanoGTK include files and also the objects must be linked with the NanoGTK libraries instead of the X11 counter parts. NanoGTK is licensed under LGPL. Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. 1. Installation ------------ You may install NanoGTK in any working area convenient to you but you are recommended to install NanoGTK in your home directory or /opt. If you install NanoGTK outside your home directory, you may need root priviledge for installation, i.e. you must logon as root to start the installation. We refer to the directory where NanoGTK is installed as NANOGTK_HOME. To install NanoGTK, change the current working directory to the parent directory of NANOGTK_HOME, i.e. /opt. Then run the command to extract files from the distribution archive: cd /opt tar xvzf SOMEWHERE/NanoGTK-1.0pre1/.tgz When it is done, the top directory NanoGTK should contain the following subdirectories: Application - various NanoGTK sample applications EmGdkPixbuf - Graphic library glib-1.2.7 - Glib function library gtk+-1.2.7 - Gtk+ function library microwin - Microwindow library Testbench - Testing directory zlib - Compression algorithm library 2. Using the emulation environment ------------------------------- To run the sample applications, change the current working directory to NANOGTK_HOME/Testbench. In this directory, you are provided with a complete emulation environment to run NanoGTK desktop and sample applications. You can also run your own applications provided that these applications are linked with NanoGTK libraries. 2.1 Configure desktop If this is the first time you run the desktop, you will need to install the executables and supporting files. To install the files, first make sure you are in NANOGTK_HOME/Testbench and then type the command: ./local/bin/configure.sh When it is done, the file Testbench/config/deskman.cfg is created. This is the current desktop configuration. Besides all applications that can be found in NANOGTK_HOME/Application are included in the desktop. You may now start running the desktop. 2.2 Running the desktop An application cannot run on its own. It requires a nano-X server, and optionally a window manager and desktop manager. To run everying as configured, first make sure you are in NANOGTK_HOME/Testbench and then type the command: ./startx You should see a number of icons appear in the upper area of desktop. Each icon represents an application. The size of the Microwindow is defined when nano-X server is compiled. Therefore, you should not resize the window manually. 2.3 Stopping the desktop To terminate the desktop, place the mouse pointer in the desktop window and hit the ESC key twice. You should not close the desktop by hitting the interrupt key Ctrl-C or selecting the destroy icon on the Microwindow toplevel window. As this may terminate the desktop with some child processes continue to run in the background. Consequently, next time when you start the desktop again, the windows may not be shown properly. 2.4 Reconfigure the desktop If you are going to modify an existing application in the Application directory, there is no need to reconfigure the files in the Testbench directory since the program files in this directory are symbolic link to the executables in the Application directory. You should close the desktop before recompiling an existing application. If you have created a new application in the Application directory, you will need to install the new application executable and setup files so that the desktop manager knows about it. To configure automatically for the desktop, you should first uninstall the current configuration and then reconfigure by the commands: ./local/bin/distclean.sh ./local/bin/configure.sh If you have manually modified the file Testbench/config/deskman.cfg to make customized desktop configuration, you should rename or backup this file before automatically configuration. 2.5 Starting desktop in specific locale This x86 release comes with support for locales en_US, zh_CN.GB2312 and zh_TW.Big5. To start desktop in specific locale, you must specify a flag on the command line as: US English: ./startx Traditional Chinese: ./startx -big5 Simplified Chinese: ./startx -gb Japanese: ./startx -jis Korean: ./startx -ks 3. Running application without deskop ---------------------------------- You can run an application with the nano-X server only. In order to run NanoGTK properly, you must set a few environment variables and also change your command search path if you are not using the facilities in the Testbench directory. Most default installation provide sh or bash shell for the user. However, some of you may be using csh instead. Set up your environment as described next. 3.1 Setup your environment for sh or bash shell: export NANOGTK_HOME=/opt/NanoGTK export LD_LIBRARY_PATH= \ ${NANOGTK_HOME}/EmGdkPixbuf/lib-x86: \ ${NANOGTK_HOME}/microwin/lib-x86: \ ${NANOGTK_HOME}/glib/lib-x86: \ ${NANOGTK_HOME}/gtk+/lib-x86 export PATH=\ ${NANOGTK_HOME}/glib/bin-x86:\ ${NANOGTK_HOME}/gtk+/bin-x86:$PATH You should set NANOGTK_HOME to the actual installed directory. 3.s Setup your environment for csh: setenv NANOGTK_HOME /opt/NanoGTK setenv LD_LIBRARY_PATH \ ${NANOGTK_HOME}/EmGdkPixbuf/lib-x86\ ${NANOGTK_HOME}/microwin/lib-x86:\ ${NANOGTK_HOME}/glib/lib-x86:\ ${NANOGTK_HOME}/gtk+/lib-x86 setenv PATH \ ${NANOGTK_HOME}/glib/bin-x86:\ ${NANOGTK_HOME}/gtk+/bin-x86:$PATH You should set NANOGTK_HOME to the actual installed directory. 3.3 Starting program Before starting a program, the nano-X server must be started first. To start a program, you may type the command: nano-X & my_prog 4.0 Testbench directory ------------------- The Testbench directory provides an emulation environment to run the NanoGTK desktop and applications in nano-X on top of X Windows. The subdirectories in Testbench directory are: Testbench/ | |---configs/ | |---fonts/ | |---icons/ | |---programs/ | |---local/ | |---bin/ | |---etc/ | |---share/ | |---locale/ The files to be placed in these directories are: configs - Configuration files (.cfg) for deskman and applications fonts - Fonts for nano-X icons - System and application icon data files (.gif and .xpm) programs - Application executable files (symbolic links only) local - Miscellaneous files for running applications You should use the configure script in the Testbench/local/bin directory to generate deskman.cfg, copy application configure and icon files, and also setup links to executables. 4.1 Adding new applications If you are adding a new application to the desktop, you should create a directory for this new application in NANOGTK_HOME/Application. All the source and build files should be saved under this directory. For example, suppose you are developing a new application named New_App for PC. The executable running on x86 processor must be saved in: NANOGTK_HOME/Application/New_App/bin-x86 Besides, you will also need to create a subdirectory of New_App named emlinux. In this subdirectory, the configuration file, icon files and locale message files are saved in config, icon and locale respectively. You may copy executable and other runtime files from New_App/emlinux directory to Testbench subdirectories manually. However, if you do this, you will have to edit the deskman.cfg file in Testbench/configs yourself. The easiest way to add a new application to the desktop is: - Rename the existing deskman.cfg - Run the script NANOGTK_HOME/Testbench/local/bin/configure.sh - Merge the old deskman.cfg with the newly created one (only if you have customized the file deskman.cfg) 4.2 Updating files in Testbench When you have recompiled an application which has already been added to the desktop, normally you do not need to run configure.sh again. This is because executables are links in the programs directory. However, if the application specific configuration, icon files or locale message files have been modified, you can update the files in Testbench by first running distclean.sh and then follow by configure.sh. Alternatively, you can copy these files manually to Testbench subdirectories. 5.0 References ---------- GTK+ : www.gtk.org Microwindows : www.microwindows.org NanoGTK : www.emsoftltd.com ------------------------------------------------------------------------------ Rev. 1.0pre1 June 2002