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.
<h2>Prerequisites</h2>
-You need <a href="http://trolltech.com/products/qt">Trolltechs Qt</a> free edition
-version 4.3 or any newer.<p/>
+You need <a href="http://www.qtsoftware.com/products/">Trolltech/Nokias Qt</a> Open Source edition
+version 4.4 or any newer.<p/>
If you want to secure your connection with HTTPS you need
<a href="http://www.openssl.org/">OpenSSL</a> installed and Qt needs to be built with
-SSL-support.
+SSL-support.<p/>
+
+The autoupdate function of MagicSmoke needs <a href="http://gmplib.org/">GNU MP</a> 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 <tt>gmp.h</tt> is in the default include path of the compiler.<p/>
+
+You need a C++ compiler that works with Qt. I usually recommend GCC 4.x for Linux and other Unixoid systems and <a href="http://www.mingw.org/">MinGW</a> with GCC 3.4 for Windows. If you have a Mac please let me know what combination works best... ;-)
<h2>Building</h2>
-Go to the <tt>src</tt> directory and there call QMake and Make:
-<pre>
-sh$ qmake
-sh$ make
-</pre>
+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).<p/>
+
+Make sure that the correct version of QMake is in your PATH (you can check this by executing <tt>qmake -version). Also note that MagicSmoke and Qt have to be compiled with the same compiler.<p/>
+
+Go to the main directory of MagicSmoke. There you will find a file called <tt>Makefile.unix</tt> for Linux and other Unixoid systems and <tt>Makefile.mingw</tt> 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).<p/>
+
+Unixoid systems:<br/>
+<tt>make -f Makefile.unix <i>rule</i></tt><p/>
+
+Windows with MinGW:<br/>
+<tt>mingw32-make -f Makefile.mingw <i>rule</i></tt><p/>
-(On Windows replace <tt>make</tt> with <tt>mingw32-make</tt>.)<p/>
+If you omit the <tt><i>rule</i></tt> parameter make will do a complete build. The following rules are available:<p/>
-This will build the <tt>msmoke</tt> binary (under Windows it will be located in the <tt>release</tt> folder), which can be used immediately.
+<table frame="1" border="1">
+<tr><td><b>Rule</b></td><td><b>Description</b></td></tr>
+<tr><td>all</td><td>complete build</td></tr>
+<tr><td>woc</td><td>only the web object compiler</td></tr>
+<tr><td>wob</td><td>web object compiler and preprocessing of common components</td></tr>
+<tr><td>server</td><td>everything that is necessary for the server</td></tr>
+<tr><td>client</td><td>the client</td></tr>
+<tr><td>sdoc</td><td>source documentation (not included in all), requires doxygen</td></tr>
+</table>
<h2>Shipping</h2>
-When installing Magic Smoke on another computer you have to make sure that all required libraries are there too. You can <a href="http://silmor.de/32">find out</a> what these libraries are using standard tools, like <tt>ldd</tt> (Unix/Linux), <tt>objdump -x</tt> or <tt>dumpbin /depends</tt> on Windows, or <tt>otool -L</tt> on MacOS. Additional to those you need to copy libssl for OpenSSL.<p>
+When installing Magic Smoke on another computer you have to make sure that all required libraries are there too. You can <a href="http://silmor.de/32">find out</a> what these libraries are using standard tools, like <tt>ldd</tt> (Unix/Linux), <tt>objdump -x</tt> or <tt>dumpbin /depends</tt> on Windows, or <tt>otool -L</tt> on MacOS.<p>
(to be continued)
\ No newline at end of file
<ul>
<li>Using the Web-Interface</li>
-<li>Using the Client Program</li>
-<li>Configuring the Client Program</li>
+<li>Using the Client Program - see the built-in help of the client.</li>
</ul>
<h2>Building/Installing Magic Smoke</h2>
to be written
<ul>
-<li><a href="prog_protocol.html">Protocol Documentation</a></li>
+<li>The MagicSmoke <a href="prog_arch.html">Architecture</a></li>
+<li>Client-Server-<a href="prog_protocol.html">Protocol Documentation</a> (this version of the protocol is obsolete and only supported for a short transition period)</li>
+<li>The <a href="prog_woc.html">Web Object Compiler</a></li>
</ul>
<h2>Preparation</h2>
<ol>
+<li><a href="build_prog.html">Build</a> at least the server components.</li>
<li>create a database on MySQL (eg. <tt>create database smokedb</tt>)</li>
<li>create a database user (eg. <tt>create user smokeuser</tt>)</li>
<li>give this user full access to this database (eg. <tt>grant all on smokedb.* to smokeuser</tt>)</li>
All files needed for Web-Installation are in the www-subdirectory.
+<h3>Installation on an ISP Account</h3>
+
+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.<p>
+
+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.<p>
+
+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 <tt>phpinfo()</tt> 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.
+
<h2>Configuration</h2>
Copy the <tt>config.php.template</tt> file to <tt>config.php</tt>, then modify it to suit your
$db->setAdminPassCode("Admin","SmokeInMyEye");
</pre>
-This call sets the web-user and web-passcode for the <tt>admin.php</tt> 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 <tt>admin.php</tt> 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.
<h3>Client Authentication and Session Configuration</h3>
--- /dev/null
+<html>
+<title>Magic Smoke Architecture</title>
+</head>
+<body>
+<h1>Magic Smoke Architecture</h1>
+
+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.<p>
+
+The stand-alone client is implemented in Qt to run natively on each platform.<p>
+
+Furthermore MagicSmoke in organized in the classic three-tier layout:<p>
+
+<table frame="1" border="1">
+<tr><td>Layer 3<td>Qt-Client or Browser</tr>
+<tr><td><i>(Interface)</i><td><i>HTTP Protocol</i></tr>
+<tr><td>Layer 2<td>PHP/Apache based Server</tr>
+<tr><td><i>(Interface)</i><td><i>DB-Protocol</i></tr>
+<tr><td>Layer 1<td>(MySQL) Database</tr>
+</table><p>
+
+<h2>Server: Overall Architecture</h2>
+
+
+
+<h2>Server: Machine Interface</h2>
+
+<h2>Server: Browser Interface</h2>
+
+
+<h2>Qt based Client</h2>
+
+
+</html>
\ No newline at end of file
--- /dev/null
+<html>
+<title>Web Object Compiler</title>
+<body>
+<h1>Web Object Compiler</h1>
+
+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.<p>
+
+<table frame="1" border="1">
+<tr><td>Layer 3<td>Client Presentation Layer</tr>
+<tr><td rowspan="3"><i>Communication Interface</i><td><i><b>Server Abstraction Layer</b></i></tr>
+ <tr><td><i>Network Protocol (eg. HTTP)</i></tr>
+ <tr><td><i><b>Communication Abstraction Layer</b></i></tr>
+<tr><td>Layer 2<td>Server Business Logic</tr>
+<tr><td rowspan="2"><i>Data Interface</i><td><i><b>Database Abstraction Layer</b></i></tr>
+ <tr><td><i>DB-Protocol (eg. LibMySQL)</i></tr>
+<tr><td>Layer 1<td>Database (eg. MySQL)</tr>
+</table>
+<i>Three Tier Architecture</i><p>
+
+<h2>Database Abstraction Layer</h2>
+
+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.
+
+<h2>Communication Abstraction Layer</h2>
+
+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.
+
+<h2>Business Logic: Mapping - the Trivial Case</h2>
+
+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....
+
+<h2>Server Abstraction Layer</h2>
+
+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.
+
+
+</html>
\ No newline at end of file
projects / web/konrad/smoke.git / commitdiff