From: konrad Date: Sun, 1 Feb 2009 17:43:27 +0000 (+0000) Subject: bringing docu up to date, draft of woc docu X-Git-Url: http://git.silmor.de/gitweb/?a=commitdiff_plain;h=a1e02a64a304b0716898492f6c5cc424937877ab;p=konrad%2Fsmoke.git bringing docu up to date, draft of woc docu git-svn-id: https://silmor.de/svn/softmagic/smoke/trunk@258 6e3c4bff-ac9f-4ac1-96c5-d2ea494d3e33 --- diff --git a/README b/README index 72b77d1..b8c9ce7 100644 --- a/README +++ b/README @@ -3,7 +3,11 @@ Magic Smoke Ticketing System - README Magic Smoke was written to keep track of tickets for events (like concerts or theatric plays), sell them online or through retailers. It does not keep -your books or handle any financial transactions. Mind the warning below. +your books or handle any financial transactions. + +This is NOT a system for support tickets. + +Mind the warning below. See the HTML files in the doc directory for more information. diff --git a/doc/build_prog.html b/doc/build_prog.html index 63c139c..b2f905c 100644 --- a/doc/build_prog.html +++ b/doc/build_prog.html @@ -6,27 +6,45 @@

Prerequisites

-You need Trolltechs Qt free edition -version 4.3 or any newer.

+You need Trolltech/Nokias Qt Open Source edition +version 4.4 or any newer.

If you want to secure your connection with HTTPS you need OpenSSL installed and Qt needs to be built with -SSL-support. +SSL-support.

+ +The autoupdate function of MagicSmoke needs GNU MP for signature checks. Most Linux distributions come with GNU MP as standard packages, there are pre-compiled packages at various locations in the net - make sure you use one that matches your compiler. Make sure GNU MP is installed so that gmp.h is in the default include path of the compiler.

+ +You need a C++ compiler that works with Qt. I usually recommend GCC 4.x for Linux and other Unixoid systems and MinGW with GCC 3.4 for Windows. If you have a Mac please let me know what combination works best... ;-)

Building

-Go to the src directory and there call QMake and Make: -
-sh$ qmake
-sh$ make
-
+Both server and client depend on some shared code that is pre-compiled into some of their components. So it is easiest to do a complete build (unless you are familiar with the sources).

+ +Make sure that the correct version of QMake is in your PATH (you can check this by executing qmake -version). Also note that MagicSmoke and Qt have to be compiled with the same compiler.

+ +Go to the main directory of MagicSmoke. There you will find a file called Makefile.unix for Linux and other Unixoid systems and Makefile.mingw for MinGW/Windows installations. There are a few lines at the start of those files that you can adjust to better match your system (defaults should be fine for most cases).

+ +Unixoid systems:
+make -f Makefile.unix rule

+ +Windows with MinGW:
+mingw32-make -f Makefile.mingw rule

-(On Windows replace make with mingw32-make.)

+If you omit the rule parameter make will do a complete build. The following rules are available:

-This will build the msmoke binary (under Windows it will be located in the release folder), which can be used immediately. + + + + + + + + +
RuleDescription
allcomplete build
woconly the web object compiler
wobweb object compiler and preprocessing of common components
servereverything that is necessary for the server
clientthe client
sdocsource documentation (not included in all), requires doxygen

Shipping

-When installing Magic Smoke on another computer you have to make sure that all required libraries are there too. You can find out what these libraries are using standard tools, like ldd (Unix/Linux), objdump -x or dumpbin /depends on Windows, or otool -L on MacOS. Additional to those you need to copy libssl for OpenSSL.

+When installing Magic Smoke on another computer you have to make sure that all required libraries are there too. You can find out what these libraries are using standard tools, like ldd (Unix/Linux), objdump -x or dumpbin /depends on Windows, or otool -L on MacOS.

(to be continued) \ No newline at end of file diff --git a/doc/index.html b/doc/index.html index 22d0126..bac8dbb 100644 --- a/doc/index.html +++ b/doc/index.html @@ -11,8 +11,7 @@ to be written:

Building/Installing Magic Smoke

@@ -33,7 +32,9 @@ to be written: to be written diff --git a/doc/install_web.html b/doc/install_web.html index 99f4a06..d7bf2ae 100644 --- a/doc/install_web.html +++ b/doc/install_web.html @@ -29,6 +29,7 @@ by PHP and you still need to configure the web server.

Preparation

    +
  1. Build at least the server components.
  2. create a database on MySQL (eg. create database smokedb)
  3. create a database user (eg. create user smokeuser)
  4. give this user full access to this database (eg. grant all on smokedb.* to smokeuser)
    5. @@ -38,6 +39,14 @@ by PHP and you still need to configure the web server. All files needed for Web-Installation are in the www-subdirectory. +

    Installation on an ISP Account

    + +If you are using an account at an ISP you usually don't get much access to the server. You still have to make sure that you have support for all required components.

    + +You will usually get a MySQL database and a matching user name from your provider. You can skip the basic DB creation above, configure the parameters you got from the provider and then go on as normal.

    + +Some providers install several versions of PHP in parallel and detect what version you use by the file suffic that you are using. Try the phpinfo() call from above with different file extensions (eg. .php, .php5) to find out what is needed to be interpreted as a PHP 5.x script. Rename exactly the scripts index.php, admin.php, and machine.php to the correct suffix. Do NOT change any other script names - these are the only ones executed directly and they rely on the other script names still being as delivered. +

    Configuration

    Copy the config.php.template file to config.php, then modify it to suit your @@ -73,7 +82,7 @@ There is one option stored in the DB-Engine that is only used for database creat $db->setAdminPassCode("Admin","SmokeInMyEye"); -This call sets the web-user and web-passcode for the admin.php script. After installing the system this line should be commented to prevent anyone from destroying the database or installing more admin users. +This call sets the web-user and web-passcode for the admin.php script. After installing the system this line should be commented to prevent anyone from destroying the database or installing more admin users. Change the second parameter (password) to something else, so I won't be able to guess your admin password in case you forget to comment it.

    Client Authentication and Session Configuration

    diff --git a/doc/prog_arch.html b/doc/prog_arch.html new file mode 100644 index 0000000..e17aec1 --- /dev/null +++ b/doc/prog_arch.html @@ -0,0 +1,33 @@ + +Magic Smoke Architecture + + +

    Magic Smoke Architecture

    + +MagicSmoke uses a basic Client-Server-Architecture with the server being implemented in PHP to run on a web server (usually Apache) and two client modes: a stand-alone application for internal users and a web browser interface for customers. Accordingly the server has two interfaces to face each of those clients.

    + +The stand-alone client is implemented in Qt to run natively on each platform.

    + +Furthermore MagicSmoke in organized in the classic three-tier layout:

    + + + + + + + +
    Layer 3Qt-Client or Browser
    (Interface)HTTP Protocol
    Layer 2PHP/Apache based Server
    (Interface)DB-Protocol
    Layer 1(MySQL) Database

    + +

    Server: Overall Architecture

    + + + +

    Server: Machine Interface

    + +

    Server: Browser Interface

    + + +

    Qt based Client

    + + + \ No newline at end of file diff --git a/doc/prog_woc.html b/doc/prog_woc.html new file mode 100644 index 0000000..d2e8dbc --- /dev/null +++ b/doc/prog_woc.html @@ -0,0 +1,38 @@ + +Web Object Compiler + +

    Web Object Compiler

    + +In a classic three-tier architecture (see below) there are two interface layers: data and communication. +The Web Object Compiler (woc) helps implementing these three-tier architecture interfaces.

    + + + + + + + + + + +
    Layer 3Client Presentation Layer
    Communication InterfaceServer Abstraction Layer
    Network Protocol (eg. HTTP)
    Communication Abstraction Layer
    Layer 2Server Business Logic
    Data InterfaceDatabase Abstraction Layer
    DB-Protocol (eg. LibMySQL)
    Layer 1Database (eg. MySQL)
    +Three Tier Architecture

    + +

    Database Abstraction Layer

    + +The Database Abstraction Layer is the servers lower bound towards the database. It is a simple translation of the database structure into usable PHP objects. + +

    Communication Abstraction Layer

    + +The Communication Abstraction Layer is the servers upper bound towards the client. It hides the complexities of serializing data onto the network transport protocol by providing communication classes that do this automatically. + +

    Business Logic: Mapping - the Trivial Case

    + +In some cases the Business Logic is a trivial case of translating a database object into a communication object. For these cases a simple mapping can be formulated.... + +

    Server Abstraction Layer

    + +This is the clients lower bound towards the server. It takes care of basic tasks like authentication, communication, serializing and deserializing data and keeping a cache of some important objects. + + + \ No newline at end of file