This is xnee_develop.info, produced by makeinfo version 4.0 from
xnee_develop.texi.

INFO-DIR-SECTION Miscellaneous
START-INFO-DIR-ENTRY
* Xnee_develop: (xnee_develop).	Xnee Development Guide
END-INFO-DIR-ENTRY

   This file documents Xnee This file is written by Henrik Sandklef
2002-10-xx Copyright 2002 Henrik Sandklef


File: xnee_develop.info,  Node: Top,  Up: (dir)

Xnee Development Guide
**********************

   This file documents how to develop Xnee.

Introduction
************

Short description
=================

   Xnee can record and replay an X session. Xnee also has the ability to
distribute events to multiple displays.

Xnee features
=============

   Test tool Instead of performing test cases for a GUI (or CLI
program) cases over and over again, the test cases can be automated.
Simply record a user session and replay it later.

   Performance test tool 	If you want to simulate lots of
simultaneous users in a network (or 	a local machine) you can use Xnee.
Simply record a (or many) users 	sessions and start multiple instances
of Xnee.

   Demo tool 	You can use Xnee to demonstrate the features of
your program. Simply 	record a user session and replay it later.

   Distribution tool 	If you want to send over your mouse/keyboard
actions to another display 	you can use the built-in
distribution mechanism in Xnee.

Background
==========

   In order to verify that a program does the job it's supposed to do,
certain tests have to be made. These tests are, IMHO, perhaps the most
boring things a programmer can do. With xnee the testcase(s) can be
recorded and later on replayed. Xnee can also distribute events (both
when recording and replaying) to other displays.

   Initially, Xnee was made to release the programmer (that's me) from
the burdon of testing, who hopefully will be writing free software
instead (I am doing that), from this burdon.

How does it work
================

   Xnee uses X Windows System. For more information about this lovely
system, go to :
   * X.org                   <http://www.x.org>

   * XFree86 		<http://www.xfree86.org>

   * Ken Lee's X site	<http://www.rahul.net/kenton/xsites.html>

   Xnee receives X11 protocol data (e g XEvents) from an X server and
prints them to a file (or stdout). Mouse and kwyboard actions generate
device events.  These events can be relpayed. Other X11 data can also
recorded. These data is used when replaying to synchronise. This is not
only useful but essential.  We can not replay or regenerate
keyboard-events to a window before it's ready to "receive" events. By
recording data other than device events

Xnee Development Overview
*************************

   It is assumed that the reader has the read through the Xnee Manual.

   It has been one of the goals with Xnee to deliver an API that us
easy to use and object-oriented as much as C allows. As an example you
don't have to allocate any of the structs in Xnee or any other for that
matter. It is all hanlde by the functions in the Xnee library.

Xnee components
===============

   Xnee is made up of
   * library (libxnee)

   * a command line tool (xnee)
   The library is seperated from the binary to make the development of
a GUI frontend easier.

Xnee library
============

   The library itself can bee seen as consisting of three parts.

base
----

   This part of Xnee library contains the macros (define), structs and
common functions (e.g data printing functions, data allocating
functions).

   Base is made up of the following files
   * xnee.h & xnee.c         contains the structs, macros and
     prototypes (no, not declarations) and definitions of the common
     functions

   * print.h & print.c         Xnee specific printing functions used
     throughout Xnee.

record
------

   Record is made up of the following files:
   * xnee_record.h & xnee_record.c         functions specific for
     recording

replay
------

   Replay is made up of the following files:
   * xnee_record.h & xnee_record.c         functions specific for
     recording

Xnee command
============

   The command line program Xnee consists of

parser
------

   * parse.h & parse.c         parser for the command line options,
     help printouts etc

main
----

   * main.c         main program. Simply consists of invocations of
     functions in Xnee library and in the parser.

Making of a future Xnee GUI frontend
====================================

   An Xnee GUI fronted can be made in any of the following ways
   * invoikng xnee using the execv* calls         This GUI would build
     up an Xnee command line that is eventually executed.

   * using libxnee         User settings are used with Xnee library to
     set up the Xnee structs and there after use any of the Xnee
     replay/record functions.

Xnee requirements
=================

   It is assumed that you're familiar with X11. If not go to the
following URLs and read:
   * X.org                   <http://www.x.org>

   * XFree86 		<http://www.xfree86.org>

   * Ken Lee's X site	<http://www.rahul.net/kenton/xsites.html>

   Xnee records X11 data using RECORD extension. For more details on
that look for the specifications of the extension:  	record.ps
recordlib.ps

   Xnee fakes/replays events using XTest extension. For more details on
that look for the specifications of the extension:  	xtest.ps
xtestlib.ps

Downloading Xnee
****************

   Xnee can be downloaded using:
   * CVS

   * http

   The instructions for downloading can be found at
<http://sourceforge.net>

http download
=============

   from Sourceforge.  Go to the following URL:
<http://sourceforge.net/projects/xnee> and follow the Xnee Download link

CVS download
============

Anonymous download
------------------

      cvs -d:pserver:anonymous@cvs.xnee.sourceforge.net:/cvsroot/xnee login
     When asked for password just type <ENTER> (that is a blank password)
      cvs -z3 -d:pserver:anonymous@cvs.xnee.sourceforge.net:/cvsroot/xnee co xnee

Developer download
------------------

     export CVS_RSH=ssh
     cvs -z3 -d:ext:developername@cvs.xnee.sourceforge.net:/cvsroot/xnee co xnee

Development requirements for Xnee
*********************************

   Apart from the obvious operating system and a compiler the following
softwares are needed when developing Xnee.
   * X11 development environment         this must include the RECORD
     and XTEST extensions

   * auto*         aclocal, automake, autoconf (GNU software)

   * doygen         a documentation system

   * rpm         RedHat's packet manager

   * GNU make

   One can develop Xnee without auto* & rpm. Rpms, and tar.gz files
cannot be built for release at <Soureforge.net> without them.

Building Xnee
*************

   Xnee can be built the following ways:
   * from CVS sources

   * from tar.gz file

Build Xnee from CVS sources
===========================

Using autotools from GNU
------------------------

   * make -f Makefile.cvs

   * ./configure

   * make

   * make install

Not using autotools from GNU
----------------------------

   * make -f Makefile.xnee
   Installation has to made by you. You're on your own here!

Build Xnee from tar.gz (gzipped tar file)
=========================================

Using autotools from GNU
------------------------

   * ./configure

   * make

   * make install

Not using autotools from GNU
----------------------------

   * make -f Makefile.xnee
   Installation has to made by you. You're on your own here!

Document test
=============

   Open the documents aa described below and make sure they look good
(formatting correct etc) and that they have correct version number,
date etc.
        Document type                    Todo
        man                              Use man:
                                         mkdir tmp
                                         pushd tmp
                                         mkdir man/man1/
                                         cp ../doc/xnee.1 man/man1/
                                         man -M . xnee
                                         [make sure it is correct]
                                         popd
                                         \rm -fr tmp
        info                             Use info:
                                         info -f doc/xnee.info
                                         info -f doc/xnee_develop.info
        txt                              Use a pager (e.g less):
                                         less doc/xnee_man.txt
        pdf                              Use a pdf reader (e.g xpdf)
                                         xpdf doc/xnee.pdf
                                         xpdf doc/xnee_develop.pdf
        ps                               Use a ghostscript reader (e.g
                                         ggv):
                                         ggv doc/xnee.ps
                                         ggv doc/xnee_develop.ps
        html                             Use a browser (e.g galeon):
                                         galeon file:`pwd`/doc/xnee.html
                                         galeon
                                         file:`pwd`/doc/xnee_develop.html
   A script is ditributed with xnee to speed this test up a bit.  Use
'doctest.sh' in the Xnee root directory

Regression test
---------------

   Perfom the examples in the Examples section of the manual.

Releasing x new version of Xnee
*******************************

   To release Xnee the following has to made:
   * Update NEWS, TODO

   * Update Version information (doc/version.texi configure.in)

   * Test the changes (including version number)

   * Make sure that all documents is correct

   * Do a regression test of Xnee

   * Check in to the CVS repository

   * Tag in CVS with version

   * 1) Make distribution (make dist) and rpms (xxxx)

   * or

   * 2) Use the build script (./build.sh -rpm)

   * Test installation of SRPM and RPM

   * Test build & installation of tar.gz

   * Release the files at <htt://sourceforge.net>

   * Make a release at <htt://freshmeat.net>

   * Update the Xnee homepage <http://xnee.sourceforge.net>

Xnee FAQ
********

`Can Xnee record more than one display?'
     No, but I am considering adding the functionality (see the TODO
     file)

`Will you put up a source tree so that I can join ?'
     You can find a CVS tree (soon) at Sourceforge.   You are more than
     welcome to join

`Can I write a GUI frontend for you ?'
     Yes !

`What license is Xnee released under ?'
     GPL  <http://www.gnu.org/copyleft/gpl.html>

`Why GPL?'
     I consider my programs as:
        * a fun way for me to (hopefully) become a better programmer

        * a sort of payback for my operating systems (GNU/Linux and
          OpenBSD)

        * a way to make free operating systems better and more widely
          used than XXX
      And of course I think it would be a great kick for my ego to have
     other  people using my programs (especially if the alternative is
     a non-free program on a non-free operating system).

`Why the name Xnee?'
     I wanted to use a recursive acronym, as GNU ("GNU's Not Unix').
     After having read the Wine documentation, I thought that Xnee is
     not an Event Emulator would work fine. Since Xnee is Not an Event
     Emulator but rather a XEvent generator. Emulation is not part of
     the game here....    .... it just sounds nice!

`Can you add xxx functionality to Xnee'
     Send an email to <xnee@sandklef.com> and I'll consider it.

`When starting Xnee I get noticed that I am missing RECORD extension'
     Your X server doesn't have the RECORD extension either loaded or
     compiled. TO solve this you have to, depending on what Xserver you
     have do the following:

        * XFree86 4.0 and higher Make sure that the RECORD extension is
          loaded. This is done by letting the Module section in the X
          config file (e.g /etc/X11/XF86Config-4) look something like:

          `Section "Module"'
          `Load  "dbe"             # Double-buffering'
          `Load  "GLcore"          # OpenGL support'
          `Load  "dri"             # Direct rendering infrastructure'
          `Load  "glx"             # OpenGL X protocol interface'
          `Load  "extmod"          # Misc. required extensions'
          `Load  "v4l"             # Video4Linux'
          `# Load  "pex5"          # PHIGS for X 3D environment
          (obsolete)'
          `Load  "record"  # X event recorder'
          `# Load  "xie"           # X Image Extension (obsolete)'
          `# You only need the following two modules if you do not use
          xfs.'
          `# Load  "freetype"       # TrueType font handler'
          `# Load  "type1"         # Adobe Type 1 font handler'
          EndSection

          The important load directive (in this case) is the following
          line
          `Load  "record"  # X event recorder'
        * X.org, XFree86 (3.3 and lower)  or any other Xserver
          Recompile and reinstall the Xserver and make sure that RECORD
          extension is built into the Xserver. Please look at the
          documentation from your Xserver "vendor" on how to do that.

`Where do I send questions?'
     <xnee@sandklef.com>

* Menu:


Tag Table:
Node: Top323

End Tag Table
