#
# 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.24.0 2022-12-24
# @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 Preparation
2.2 General
2.3 User Interface
2.4 Serial Interface
2.5 Socket
2.6 Tools

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

4 Development
4.1 Make Targets
4.2 API

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

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

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

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
    clang-format
    cppcheck (cppcheck-gui)
    valgrind (graphviz, kcachegrind, valkyrie)
    python3, python-is-python3, python3-pip (for cybol api documentation generation in cmake target and build scripts)

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 Preparation
_______________

Change into the base directory of the cybol application and execute
cyboi from there, giving the "run.cybol" file as argument, for example:

    cd /home/cybop/examples
    ../src/controller/cyboi application/repertoire/run.cybol

    cd /home/cybop/tools
    ../src/controller/cyboi api-generator/run.cybol

If cybop was installed as debian package or the system path got adapted,
then the cyboi interpreter may be executed directly:

    cd /home/cybop/examples
    cyboi helloworld/simple/run.cybol

2.2 General
___________

    cyboi exit/simple/run.cybol
    cyboi shell_command/list_directory_contents/run.cybol
    cyboi control_flow/programme_execution/run.cybol
    cyboi control_flow/programme_execution_via_signal/run.cybol
    cyboi helloworld/simple/run.cybol
    cyboi mathematics/addition/run.cybol
    cyboi counter/simple/run.cybol

- TODO (currently not working, outdated and to be updated applications):

    cyboi addition_dynamic_model/run.cybol
    cyboi addition_dynamic_model_with_root/run.cybol
    cyboi addition_static_model/run.cybol
    cyboi addition_using_serialisation/run.cybol
    cyboi double/run.cybol
    cyboi date/run.cybol
    cyboi get_count/run.cybol
    cyboi counter_static_model/run.cybol
    cyboi counter_storage/run.cybol

    cyboi time_output_1/run.cybol
    cyboi time_output_2/run.cybol
    cyboi time_output_3/run.cybol
    cyboi addition_using_indices/run.cybol
    cyboi index_usage/run.cybol
    cyboi knowledge_tree_access/run.cybol

2.3 User Interface
__________________

    cyboi helloworld/tui/run.cybol
    cyboi user_interface/tui_control/run.cybol

- TODO (currently not working, outdated and to be updated applications):

    cyboi tui/run.cybol
    cyboi gui/run.cybol
    cyboi wui/run.cybol
    cyboi ui/run.cybol

2.4 Serial Interface
____________________

- TODO (currently not working, outdated and to be updated applications):

    cyboi indoor_climate/run.cybol (CAUTION! Works only together with the corresponding microcontroller device via usb serial port.)
    cyboi adc/run.cybol (CAUTION! Works only together with the corresponding microcontroller device via usb serial port.)

2.5 Socket
__________

    cyboi internet/socket_server/run.cybol (start socket_client in separate console afterwards)
    cyboi internet/socket_client/run.cybol (start socket_server in separate console before)
    cyboi internet/www_server_static/run.cybol (open url http://localhost:1971/index.html in webbrowser)
    cyboi internet/www_server_dynamic/run.cybol (open url http://localhost:1971/?action=greet-world in webbrowser)

- TODO (currently not working, outdated and to be updated applications):

    cyboi application/presence/run.cybol (open url http://localhost:1971/?action=send-index in webbrowser)

2.6 Tools
_________

    cd /home/cybop/tools

    cyboi api-generator/run.cybol

- TODO (currently not working, outdated and to be updated applications):

    cyboi integer_state_cyboi_model_generator/run.cybol
    cyboi field_description_xdt_model_generator/run.cybol
    cyboi xdt_field_description_serialiser_generator/run.cybol

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:

    make

- Create the cyboi binary only:

    make cyboi

Make target overview:

    make clean
    make cyboi
    make api
    make test
    make

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.

3.3.1 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

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

3.3.3 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 Make Targets
________________

See file "build/release.txt" for possible make targets and tool usage.

4.2 API
_______

- Check out python scripts:

    cd cybop/build/
    git clone https://github.com/EnricoGallus/CybopBuildScripts.git scripts

OR:

- Update python scripts:

    cd cybop/build/scripts/
    git pull

- Generate application programming interface (api) using:

    make api

- Report bugs in python scripts (optionally, if necessary) via:

    https://github.com/EnricoGallus/CybopBuildScripts/issues

Background Information:

The "make api" command invokes the python scripts.

The python scripts collect all necessary information from the
javadoc-like comment blocks in c source code from two directories:

cybop/src/constant/format/cybol/state/
cybop/src/constant/format/cybol/logic/

The following headings are considered: Description, Examples,
Properties, Constraints.

/**
 * An example.
 *
 * Description:
 *
 * ... (free text)
 *
 * Examples:
 *
 * <node name="example_1" channel="inline" format="category/operation" model="">
 *     <node name="result" channel="inline" format="text/cybol-path" model=".result"/>
 *     <node name="operand" channel="inline" format="number/integer" model="24"/>
 * </node>
 *
 * ...
 *
 * Properties:
 *
 * - result (required) [text/cybol-path]: The ...
 * - operand (required) [text/cybol-path | number/any]: The ...
 * - count (optional) [text/cybol-path | number/integer]: The ...
 *
 * Constraints for Property XY:
 *
 * - delimiter (optional) [text/plain]: The separator ...
 * - header (optional) [logicvalue/boolean]: The ...
 */

The python scripts write the collected categories into the files:
"cybop/doc/cybol/api/state.txt" and "cybop/doc/cybol/api/logic.txt".

Further, a number of cybol (xml) files gets generated in directory
"cybop/tools/api-generator/spec/".

Afterwards, the make process calls the api generator which is
written in cybol:

    cd cybop/tools
    ../src/controller/cyboi api-generator/run.cybol

It generates the final html file representing the api documentation
with state and logic.

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

