#
# Copyright (C) 1999-2022. Christian Heller.
#
# This file gives installation instructions on how to get started with cybop.
#
# Cybernetics Oriented Programming (CYBOP) <http://www.cybop.org/>
# CYBOP Developers <cybop-developers@nongnu.org>
#
# @version CYBOP 0.22.0 2022-02-22
# @author Christian Heller <christian.heller@cybop.org>
#

Contents
========

1 Installation
1.1 CYBOP
1.2 POSIX
1.3 OSX
1.4 Windows

2 Execution
2.1 Examples
2.2 Additions

3 Compilation
3.1 POSIX, OSX, Windows
3.2 Windows (GCC)
3.3 Windows (MSVC)

4 Development
4.1 Testing
4.2 Formatting
4.3 Documentation
4.4 Homepage

5 Distribution
5.1 Tagging
5.2 Packing
5.3 Debianising

6 Contribution

1 Installation
==============

1.1 CYBOP
_________

- Download latest release from:

    http://www.cybop.org/

- Extract release file, e.g.:

    tar -xvzf cybop-0.18.0.tar.gz

1.2 POSIX
_________

The following are names of Debian packages.

CYBOL application execution:
    libc6
    xorg
    freeglut3

CYBOI compilation:
    cmake (version >= 3.0.2)
    gcc
    libc-dev | libc6-dev
    xorg-dev
    libxcb1-dev (automatically installed by libx11-dev and xorg-dev; but libx11-dev "xlibs" actually not used anymore in cyboi)
    freeglut3-dev

CYBOP development (helpful, but not essential):
    subversion
    doxygen
    valgrind (graphviz, kcachegrind, valkyrie)

1.3 OSX
_______

CYBOI compilation:
    Xcode
    Xcode Command Line Tools

1.4 Windows
___________

The compilation is based on mingw and gcc.
The following are names of libraries.

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

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

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

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

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

CYBOI compilation:
    mingw32 (Debian package)
    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/

2 Execution
===========

2.1 Examples
____________

- 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.:

    ../src/controller/cyboi exit/run.cybol
    ../src/controller/cyboi exit_signal/run.cybol
    ../src/controller/cyboi exit_cybol_file/run.cybol
    ../src/controller/cyboi shell_output/run.cybol
    ../src/controller/cyboi shell_output_file/run.cybol
    ../src/controller/cyboi shell_output_sequence/run.cybol
    ../src/controller/cyboi if-else/run.cybol
    ../src/controller/cyboi shell_output_branch/run.cybol
    ../src/controller/cyboi shell_output_loop/run.cybol
    ../src/controller/cyboi shell_command_execution/run.cybol
    ../src/controller/cyboi shell_command_list_directory_contents/run.cybol
    ../src/controller/cyboi shell_command_echo_message/run.cybol
    ../src/controller/cyboi shell_command_copy_file/run.cybol
    ../src/controller/cyboi shell_command_move_file/run.cybol
    ../src/controller/cyboi shell_command_remove_file/run.cybol
    ../src/controller/cyboi shell_command_tape_archiver_unpack/run.cybol
    ../src/controller/cyboi shell_command_tape_archiver_pack/run.cybol
    ../src/controller/cyboi programme_execution/run.cybol
    ../src/controller/cyboi addition/run.cybol
    ../src/controller/cyboi addition_dynamic_model/run.cybol
    ../src/controller/cyboi addition_dynamic_model_with_root/run.cybol
    ../src/controller/cyboi addition_static_model/run.cybol
    ../src/controller/cyboi double/run.cybol
    ../src/controller/cyboi date/run.cybol
    ../src/controller/cyboi get_count/run.cybol
    ../src/controller/cyboi counter/run.cybol
    ../src/controller/cyboi counter_static_model/run.cybol
    ../src/controller/cyboi counter_storage/run.cybol
    ../src/controller/cyboi time_output_1/run.cybol
    ../src/controller/cyboi time_output_2/run.cybol
    ../src/controller/cyboi time_output_3/run.cybol
    ../src/controller/cyboi addition_using_indices/run.cybol
    ../src/controller/cyboi index_usage/run.cybol
    ../src/controller/cyboi knowledge_tree_access/run.cybol
    ../src/controller/cyboi helloworld/run.cybol
    ../src/controller/cyboi tui/run.cybol
    ../src/controller/cyboi tui_control/run.cybol
    ../src/controller/cyboi gui/run.cybol
    ../src/controller/cyboi wui/run.cybol
    ../src/controller/cyboi ui/run.cybol
    ../src/controller/cyboi addition_using_serialisation/run.cybol
    ../src/controller/cyboi indoor_climate/run.cybol (CAUTION! Works only together with the corresponding microcontroller device via usb serial port.)
    ../src/controller/cyboi adc/run.cybol (CAUTION! Works only together with the corresponding microcontroller device via usb serial port.)
    ../src/controller/cyboi socket_server
    ../src/controller/cyboi socket_client
    ../src/controller/cyboi www_server_static
    ../src/controller/cyboi www_server_dynamic
    ../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

2.2 Additions
_____________

cybop/tools/integer_state_cyboi_model_generator/
cybop/tools/field_description_xdt_model_generator/
cybop/tools/xdt_field_description_serialiser_generator/

cybop/doc/books/cybol/api/
CAUTION! Always first change into the super directory
and execute cyboi from there, e.g.:
cd cybop/doc/books/cybol
../../../src/controller/cyboi api/run.cybol
OR:
../../../src/controller/cyboi --knowledge=api/run.cybol

../src/controller/cyboi project_overview/run.cybol
Source of the following cybol-generated website:
http://www.ba-leipzig.de/index.php?id=153

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

3 Compilation
=============

3.1 Under Linux for POSIX, Linux, OSX (GCC)
___________________________________________

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

    cd /home/cybop/build

- Create architecture and operating system depending makefiles:

    cmake .

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

    make clean

- Create the cyboi binary including any test cases:

    make

- Create the cyboi binary only:

    make cyboi

3.2 Under Linux for Windows (MinGW)
___________________________________

- 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:

    i686-w64-mingw32-gcc -o src/controller/cyboi.exe src/controller/cyboi.c -static -lpthread -lws2_32 -lgdi32 -w

- OLD:

    i686-w64-mingw32-gcc -o src/controller/cyboi.exe src/controller/cyboi.c -DPTW32_STATIC_LIB -lpthread -lws2_32 -lgdi32 -w
    i586-mingw32msvc-gcc -o src/controller/cyboi.exe src/controller/cyboi.c -DPTW32_STATIC_LIB -lpthreadGC2 -lxcb -lX11 -lXau -lws2_32 -w

3.3 Under Windows for Windows (MSVC)
____________________________________

For windows compilation using Microsoft Visual Studio you will need version 2013 or higher.
Up to now XCB features are NOT supported. Other limitations you will find in the TODO list.

SVN
___

Install TortoiseSVN:
https://tortoisesvn.net/downloads.html

Configure TortoiseSVN for svn+ssh:
https://sourceforge.net/p/forge/documentation/Using%20SSH%20Keys%20with%20SVN%20on%20Windows/

Download Pageant and PuTTYgen:
https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html

Generate ssh key:
https://sourceforge.net/p/forge/documentation/SSH%20Keys/#key-generation-putty

Upload ssh key:
https://savannah.nongnu.org/

Add private key to:
pageant.exe

Checkout project:
svn+ssh://LOGIN@svn.savannah.nongnu.org/cybop/trunk

VS
__

- Open file ide/visualstudio/cyboi.sln in Visual Studio (VS)
- Adjust platform
- Compile

Adapt platform toolset version in project settings,
if VS version is higher than 2013 since otherwise,
strange compiler errors might occur.

GCC
___

References and hints:
https://stackoverflow.com/questions/39863157/cgo-sorry-unimplemented-64-bit-mode-not-compiled-in

Download installer:
http://tdm-gcc.tdragon.net/download

Execute installer:
tdm-gcc-webdl.exe

Avoid CMake errors:
Use the following command for the first cmake call:
cmake -G "MinGW Makefiles" .
instead of just:
cmake .
https://stackoverflow.com/questions/35869564/cmake-on-windows

4 Development
=============

4.1 Testing
___________

- Change into cybop's build directory e.g.:

    cd /home/cybop/build

- Run the tests by invoking either:

    make test

    or:

    ctest

    or for verbose output on stdout:

    ctest --verbose

- Optionally, run the codecoverage (needs gcov, genhtml):

    make codecoverage
    make generatehtml

4.2 Formatting
______________

- Change into cybop's build directory e.g.:

    cd /home/cybop/build

- Run the code styling clangformat which uses the .clang-format configuration:

    make clangformat

- Run the code analyzer cppcheck:

    make cppcheck

4.3 Documentation
_________________

- Change into cybop's build directory e.g.:

    cd /home/cybop/build

- Run the doxygen

    make doc

4.4 Homepage
____________

https://savannah.gnu.org/maintenance/HomepageUpload/

- upload project web pages
- use cvs for accessing the web repository (it is completely separate from any source trees)
- upload ssh key to gnu savannah portal in order to access sources
- go to local directory, e.g.:

mkdir ~/project/www
cd ~/project/www

- download cvs html tree structure:

cvs -z3 -d:ext:LOGIN@cvs.sv.gnu.org:/web/PROJECT co .

- copy all necessary files to cvs html tree using e.g.:

cp ~/tmp/index.html ~/project/www/PROJECT

- import local html tree to cvs:

cd ~/project/www/PROJECT
cvs add index.html
cvs add mydir
# (or: cvs add index.html mydir)
cvs commit

- update and commit as needed

Hint: The webpages will be updated within an hour.

5 Distribution
==============

5.1 Tagging
___________

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)

5.2 Packing
___________

- Modify the CYBOP version number in the build/cmake/packaging.cmake file:

    SET(CPACK_PACKAGE_VERSION_MAJOR "0")
    SET(CPACK_PACKAGE_VERSION_MINOR "19")
    SET(CPACK_PACKAGE_VERSION_PATCH "0")

- Change into cybop's build directory:

    cd /home/cybop/build

- Run the cpack command (file gets created in current working directory):

    cpack

- Create GPG binary signature for tarball file (file gets created in current working directory), e.g.:

    gpg -b --use-agent cybop-0.19.0.tar.gz

- Give read permissions to files, e.g.:

    chmod 644 cybop-0.19.0.tar.gz
    chmod 644 cybop-0.19.0.tar.gz.sig

- Upload files:

    scp cybop-0.19.0.tar.gz cybop-0.19.0.tar.gz.sig christian@dl.sv.nongnu.org:/releases/cybop/

See further stepwise instructions in file "dist/release.txt"!

5.3 Debianising
_______________

- Install the checkinstall Debian package:

    apt-get install checkinstall

- Execute the checkinstall command with:

    checkinstall

- Configure package answering the checkinstall questions

6 Contribution
==============

Get login at https://savannah.nongnu.org/projects/cybop/

Send login to <christian.heller@cybop.org> in order to be
    entered to project and to be given necessary access rights

Register at Mailing List <cybop-developers@nongnu.org>
    https://lists.nongnu.org/mailman/listinfo/cybop-developers

Generate SSH key on your computer

Go to your personal profile on:
    https://savannah.nongnu.org/

Upload SSH key of your computer (or many keys of all your computers)

Study source code SVN checkout (member NOT anonymous command):
    https://savannah.nongnu.org/svn/?group=cybop

Check out source code directory "trunk" from SVN:
    cd /home/projects/cybop
    svn co svn+ssh://<membername>@svn.savannah.nongnu.org/cybop/trunk .
CAUTION! Mind the SPACE and DOT at the end, after "trunk"
Possibly use svn client like "kdesvn" or "Tortoise"

Compile cyboi

Run a cybol example of your choice

