#
# This file gives installation instructions on how to get started with cybop.
#
# Cybernetics Oriented Programming (CYBOP) <http://www.cybop.org/>
# Christian Heller <christian.heller@tuxtax.de>
#
# @author Christian Heller <christian.heller@tuxtax.de>
#


CYBOP Installation
__________________

- Change into some directory, e.g.:

    cd /home/cybop

- Extract the cybop-x.x.x.tar.gz or cybop-x.x.x.tar.bz2 file, respectively, e.g.:

    tar -xvzf cybop-0.14.0.tar.gz
    tar -xvjf cybop-0.14.0.tar.bz2


Package and Library Installation POSIX
______________________________________

Debian packages for CYBOL application execution:
    xorg

Debian packages for compilation:
    autotools (autoconf, automake)
    xorg-dev
    xlibs-dev (now possibly contained in xorg-dev)
    libtool
    glut or freeglut3 or the like
    mesa etc.


Package and Library Installation Windows (GCC)
______________________________________________

Required libraries for CYBOL application execution:
    libXau-6.dll
    libxcb-1.dll
    libxcb-composite-0.dll
    libxcb-damage-0.dll
    libxcb-dpms-0.dll
    libxcb-glx-0.dll
    libxcb-randr-0.dll
    libxcb-record-0.dll
    libxcb-render-0.dll
    libxcb-res-0.dll
    libxcb-screensaver-0.dll
    libxcb-shape-0.dll
    libxcb-shm-0.dll
    libxcb-sync-0.dll
    libxcb-xfixes-0.dll
    libxcb-xinerama-0.dll
    libxcb-xtest-0.dll
    libXdmcp-6.dll
    pthreadGC2.dll

They have to be placed in either:
    %WINDIR%\system32

or in the same directory where the executable (exe) file is, e.g.:
    cybop/bin/

Debian packages for compilation:
    mingw32

Headers for compilation:
    Pthreads-Win32  (ftp://sourceware.org/pub/pthreads-win32)
    X11 (http://docs.google.com/leaf?id=0B4o4WuYAoiUTZmFiNzhiNDUtNGJkNS00OWQxLThlNzctZDcwMDQyMmQ0Y2Fh&hl=en)
    xcb

These are also available in SVN, under:
    cybop/include/i586-mingw32msvc/include/

They have to exist or be copied into:
    /usr/i586-mingw32msvc/include/

Libraries for compilation:
    libpthreadGC2 (make CROSS=i586-mingw32msvc- clean GC-inlined)
    libX11 and libXau (http://docs.google.com/leaf?id=0B4o4WuYAoiUTNTlmYmMwMDgtMzlmMC00NWNmLWE4M2UtZGIxZTQzMTQyZGZk&hl=en)
    libxcb

These are also available in SVN, under:
    cybop/include/i586-mingw32msvc/lib/

They have to exist or be copied into:
    /usr/i586-mingw32msvc/lib/


Package and Library Installation OSX
____________________________________

OSX packages for CYBOL application execution:

OSX packages for compilation:
    Xcode
    Autotools (https://gist.github.com/jellybeansoup/4192307)


CYBOI Compilation POSIX
_______________________

- Change into cybop's root directory, e.g.:

    cd /home/cybop

- Set the executable flag for the autogen file, e.g.:

    chmod ugo+x /home/cybop/autogen.sh

- Execute the configure files with:

    ./autogen.sh
    ./configure

- Clean the object files of any previous compilation (this is optional):

    make clean

- Execute the make file with:

    make

Note, that the configure process and make system are prepared to be used on
the platforms: GNU/Linux, Windows (mingw environment), Linux 64bits.
The configure script forces the 32 bits emulation mode by using special options
of gcc and other binutils. Native 32 bits Linux and Windows was not tested, however.


CYBOI Compilation Windows (GCC)
_______________________________

- Change into cybop's root directory, e.g.:

    cd /home/cybop

- Clean the object files of any previous compilation (this is optional):

    make clean

- Execute the mingw32 compiler:

    i586-mingw32msvc-gcc src/controller/cyboi.c -o src/controller/cyboi.exe -DPTW32_STATIC_LIB -lpthreadGC2 -lxcb -lX11 -lXau -lws2_32 -w


CYBOI Compilation Windows (MSVC)
________________________________


CYBOI Compilation OSX (gcc)
___________________________

- Change into cybop's root directory, e.g.:

    cd /home/cybop

- Clean the object files of any previous compilation (this is optional):

    make clean

- Execute the llvm compiler:

    make


CYBOL Application Execution
___________________________

- Set the executable flag for the cyboi binary file, e.g.:

    chmod ugo+x /home/cybop/src/controller/cyboi

- Change into the base directory of your cybol applications, e.g.:

    cd /home/cybop/examples

- Execute cyboi and give the "run.cybol" file of an application as argument, e.g.:

    /home/cybop/src/controller/cyboi exit/run.cybol
    /home/cybop/src/controller/cyboi exit_signal/run.cybol
    /home/cybop/src/controller/cyboi exit_cybol_file/run.cybol
    /home/cybop/src/controller/cyboi shell_output/run.cybol
    /home/cybop/src/controller/cyboi shell_output_file/run.cybol
    /home/cybop/src/controller/cyboi shell_output_sequence/run.cybol
    /home/cybop/src/controller/cyboi if-else/run.cybol
    /home/cybop/src/controller/cyboi shell_output_branch/run.cybol
    /home/cybop/src/controller/cyboi shell_output_loop/run.cybol
    /home/cybop/src/controller/cyboi shell_command_execution/run.cybol
    /home/cybop/src/controller/cyboi shell_command_list_directory_contents/run.cybol
    /home/cybop/src/controller/cyboi shell_command_echo_message/run.cybol
    /home/cybop/src/controller/cyboi shell_command_copy_file/run.cybol
    /home/cybop/src/controller/cyboi shell_command_move_file/run.cybol
    /home/cybop/src/controller/cyboi shell_command_remove_file/run.cybol
    /home/cybop/src/controller/cyboi shell_command_tape_archiver_unpack/run.cybol
    /home/cybop/src/controller/cyboi shell_command_tape_archiver_pack/run.cybol
    /home/cybop/src/controller/cyboi programme_execution/run.cybol
    /home/cybop/src/controller/cyboi addition/run.cybol
    /home/cybop/src/controller/cyboi addition_dynamic_model/run.cybol
    /home/cybop/src/controller/cyboi addition_dynamic_model_with_root/run.cybol
    /home/cybop/src/controller/cyboi addition_static_model/run.cybol
    /home/cybop/src/controller/cyboi double/run.cybol
    /home/cybop/src/controller/cyboi get_count/run.cybol
    /home/cybop/src/controller/cyboi counter/run.cybol
    /home/cybop/src/controller/cyboi counter_static_model/run.cybol
    /home/cybop/src/controller/cyboi counter_storage/run.cybol
    /home/cybop/src/controller/cyboi time_output_1/run.cybol
    /home/cybop/src/controller/cyboi time_output_2/run.cybol
    /home/cybop/src/controller/cyboi time_output_3/run.cybol
    /home/cybop/src/controller/cyboi addition_using_indices/run.cybol
    /home/cybop/src/controller/cyboi index_usage/run.cybol
    /home/cybop/src/controller/cyboi knowledge_tree_access/run.cybol
    /home/cybop/src/controller/cyboi helloworld/run.cybol
    /home/cybop/src/controller/cyboi tui/run.cybol
    /home/cybop/src/controller/cyboi ui_control/run.cybol
    /home/cybop/src/controller/cyboi gui/run.cybol
    /home/cybop/src/controller/cyboi addition_using_serialisation/run.cybol
    /home/cybop/src/controller/cyboi wui/run.cybol
    /home/cybop/src/controller/cyboi indoor_climate/run.cybol (CAUTION! Works only together with the corresponding microcontroller device via usb serial port.)
    /home/cybop/src/controller/cyboi adc/run.cybol (CAUTION! Works only together with the corresponding microcontroller device via usb serial port.)
*NOT FUNCTIONING YET*    /home/cybop/src/controller/cyboi http_communication/run.cybol
*NOT FUNCTIONING YET*    /home/cybop/src/controller/cyboi presence/run.cybol
*NOT FUNCTIONING YET*    /home/cybop/src/controller/cyboi character_encoding/run.cybol
*NOT FUNCTIONING YET*    /home/cybop/src/controller/cyboi document_generator/run.cybol
*NOT FUNCTIONING YET*    /home/cybop/src/controller/cyboi latex/run.cybol

To make the client-server communication work in the "http_communication" example,
type the following URL into a web browser after having started the application:
http://localhost:1971/?action=index

You may also want to have a look at the Res Medicinae project, where more CYBOL
application modules for the healthcare domain will be provided over the coming years:
http://www.resmedicinae.org/


CYBOI Development
_________________

If new files are added to the "src" or "src/controller" directories, one needs to
add their name in the EXTRA_DIST variable at the top of the respective Makefile.am
file and run autogen.sh.
In the other directories, it isn't necessary because they are completely and recursively
included during the packaging (see the EXTRA_DIST variable in Makefile.am files).

If any of the environment flags are changed in the source code, e.g.:
"LINUX_OPERATING_SYSTEM" to "GNU_LINUX_OPERATING_SYSTEM",
the Makefile.am file in the src/controller/ directory needs to be
adapted and ./autogen.sh run afterwards to update the autotools!
The "build-aux" directory and other files more are generated by autogen.sh.

The target "make clean" may always be executed before the actual "make",
but is this not necessary, since make tests the modification date of each
source file and that way knows if it has to recompile the executable.

Another point to use make targets for is the generation of the documentation.


CYBOP Distribution
__________________

- Modify the CYBOP version number in the file configure.ac, e.g.:

    AC_INIT([cybop], [0.14.0], [christian.heller@tuxtax.de])

- Change into cybop's root directory, e.g.:

    cd /home/cybop

- Run the autogen.sh script (requires autoreconf to be installed) to update all autotools files:

    ./autogen.sh

- Execute the configure file with:

    ./configure

- Produce the archives (cybop-x.x.x.tar.gz and cybop-x.x.x.tar.bz2) to be distributed:

    make dist


CYBOP Packaging
_______________

- Install the checkinstall Debian package:

    apt-get install checkinstall

- Execute the checkinstall command with:

    checkinstall

- Configure package answering the checkinstall questions


Tagging SVN
___________

Tagging and branching are very simple in SVN.
The root node of the trunk/ directory is just copied.
The graphical kdesvn application does not provide this functionality.
Therefore, adapt and use the following command line:

svn copy svn+ssh://christian@svn.savannah.nongnu.org/cybop/trunk svn+ssh://christian@svn.savannah.nongnu.org/cybop/tags/cybop-0.14.0 -m "Tag the cybop-0.14.0 release"

The https protocol as in the following example did work with the berliOS portal,
but it does NOT work with savannah:

svn copy https://christian@svn.savannah.nongnu.org/cybop/trunk https://christian@svn.savannah.nongnu.org/cybop/tags/cybop-0.14.0 -m "Tag the cybop-0.14.0 release"

It shows the following error:

svn: OPTIONS of 'https://christian@svn.savannah.nongnu.org/cybop': SSL handshake failed: SSL error: An unexpected TLS packet was received. (https://svn.savannah.nongnu.org)
