README

EVM (EVENT MACHINE) SOFTWARE PROJECT
====================================

--------------------------------------------------------------------
   Copyright 2019 Samo Pogacnik <samo_pogacnik@t-2.net>

The EVM software project is provided under the terms of the
Apache License, Version 2.0, which is available in the LICENSE file
of this project.
--------------------------------------------------------------------

The EVM (EVent Machine) software is a C library named libevm. Its public
API is defined in "libevm.h".

Features:
=========
- Check "design-notes" under docs...

Building:
=========

Prepare sources:
----------------
$ 
$ git clone https://github.com/spog/evm.git
Cloning into 'evm'...
remote: Enumerating objects: 553, done.
remote: Counting objects: 100% (553/553), done.
remote: Compressing objects: 100% (209/209), done.
remote: Total 1035 (delta 348), reused 511 (delta 313), pack-reused 482
Receiving objects: 100% (1035/1035), 235.85 KiB | 973.00 KiB/s, done.
Resolving deltas: 100% (623/623), done.
$ 

$ 
$ cd evm
evm$ 

evm$ 
evm$ ls -la
skupno 60
drwxr-xr-x  7 samo samo  4096 maj  2 12:23 .
drwxr-xr-x 19 samo samo  4096 maj  2 12:22 ..
drwxr-xr-x  2 samo samo  4096 maj  2 18:22 automk
-rw-r--r--  1 samo samo  1218 maj  2 12:22 config.mk
lrwxrwxrwx  1 samo samo    16 maj  2 12:22 configure -> automk/configure
drwxr-xr-x  2 samo samo  4096 maj  2 12:22 demos
drwxr-xr-x  2 samo samo  4096 maj  2 12:22 docs
drwxr-xr-x  8 samo samo  4096 maj  2 12:22 .git
drwxr-xr-x  3 samo samo  4096 maj  2 12:22 include
drwxr-xr-x  3 samo samo  4096 maj  2 12:22 libs
-rw-r--r--  1 samo samo 10175 maj  2 12:22 LICENSE
lrwxrwxrwx  1 samo samo    15 maj  2 12:22 Makefile -> automk/Makefile
-rw-r--r--  1 samo samo  8787 maj  2 12:22 README
-rw-r--r--  1 samo samo    20 maj  2 12:22 TODO
evm$ 

Configure:
----------
evm$ 
evm$ env BUILDIR=./build PREFIX=/usr/local ./configure
Sources absolute path (_SRCDIR_): .../evm
Build absolute path (_BUILDIR_): .../evm/build
Sources relative path (SRCDIR): .
Build relative path (BUILDIR): .build/
Target absolute installation prefix path (PREFIX): /usr/local
--
Later (in the installation command), you may provide additional absolute
target installation path prefix via the DESTDIR environment variable!
--
Creating the build directory...

No extra environment shell script provided to configure!

make: Entering directory '.../evm'
.../evm/automk/default.sh generate_makefile .
generate_makefile: .../evm/.build/./auto.mk
Done!
.../evm/automk/default.sh submakes_config .
submakes_config: .../evm/automk/configure.mk configure
make[1]: Entering directory '.../evm/libs'
.../evm/automk/default.sh generate_makefile libs
generate_makefile: .../evm/.build/libs/auto.mk
Done!
.../evm/automk/default.sh submakes_config libs
submakes_config: .../evm/automk/configure.mk configure
make[2]: Entering directory '.../evm/libs/evm'
.../evm/automk/default.sh generate_makefile libs/evm
generate_makefile: .../evm/.build/libs/evm/auto.mk
Done!
.../evm/automk/default.sh submakes_config libs/evm
make[2]: Leaving directory '.../evm/libs/evm'
make[1]: Leaving directory '.../evm/libs'
submakes_config: .../evm/automk/configure.mk configure
make[1]: Entering directory '.../evm/demos'
.../evm/automk/default.sh generate_makefile demos
generate_makefile: .../evm/.build/demos/auto.mk
Done!
.../evm/automk/default.sh submakes_config demos
make[1]: Leaving directory '.../evm/demos'
make: Leaving directory '.../evm'
evm$ 

Make:
-----
evm$ 
evm$ make
.../evm/automk/default.sh targets_make all
Sources absolute path (_SRCDIR_): .../evm
Build absolute path (_BUILDIR_): .../evm/.build
Target absolute installation prefix path (PREFIX): /usr/local
Additional absolute target installation path prefix (DESTDIR): 

No extra environment shell script provided to configure!

targets_make: .../evm/.build/./libs/auto.mk all
make[1]: Entering directory '.../evm/libs'
.../evm/automk/default.sh targets_make all
targets_make: .../evm/.build/libs/evm/auto.mk all
make[2]: Entering directory '.../evm/libs/evm'
.../evm/automk/default.sh targets_make all
targets_make: .../evm/libs/evm/libevm.mk all
make[3]: Entering directory '.../evm/libs/evm'
...
make[3]: Leaving directory '.../evm/libs/evm'
make[2]: Leaving directory '.../evm/libs/evm'
make[1]: Leaving directory '.../U2UP/evm/libs'
targets_make: .../evm/.build/./demos/auto.mk all
make[1]: Entering directory '.../evm/demos'
...
make[1]: Leaving directory '.../evm/demos'
evm$ 

Install (user):
---------------
evm$ 
evm$ env DESTDIR=$(pwd)/install make install
.../evm/automk/default.sh targets_make install
Sources absolute path (_SRCDIR_): .../evm
Build absolute path (_BUILDIR_): .../evm/.build
Target absolute installation prefix path (PREFIX): /usr/local
Additional absolute target installation path prefix (DESTDIR): .../evm/install

No extra environment shell script provided to configure!

targets_make: .../evm/.build/./libs/auto.mk install
make[1]: Entering directory '.../evm/libs'
.../evm/automk/default.sh targets_make install
targets_make: .../evm/.build/libs/evm/auto.mk install
make[2]: Entering directory '.../evm/libs/evm'
.../evm/automk/default.sh targets_make install
targets_make: .../evm/libs/evm/libevm.mk install
make[3]: Entering directory '.../evm/libs/evm'
install -d .../evm/install/usr/local/lib
install .../evm/.build/libs/evm/libevm.so .../evm/install/usr/local/lib/libevm.so
install -d .../evm/install/usr/local/include/evm
install .../evm/include/evm/libevm.h .../evm/install/usr/local/include/evm/libevm.h
make[3]: Leaving directory '.../evm/libs/evm'
make[2]: Leaving directory '.../evm/libs/evm'
make[1]: Leaving directory '../evm/libs'
targets_make: .../evm/.build/./demos/auto.mk install
make[1]: Entering directory '.../evm/demos'
.../evm/automk/default.sh targets_make install
targets_make: .../evm/demos/hello1.mk install
install -d .../evm/install/usr/local/bin
install .../evm/.build/demos/hello1_evm .../evm/install/usr/local/bin/hello1_evm
...
make[1]: Leaving directory '.../evm/demos'
evm$ 

Install (system-local):
-----------------------
evm$ 
evm$ sudo su
evm# 

evm# 
evm# make install
.../evm/automk/default.sh targets_make install
Sources absolute path (_SRCDIR_): .../evm
Build absolute path (_BUILDIR_): .../evm/.build
Target absolute installation prefix path (PREFIX): /usr/local
Additional absolute target installation path prefix (DESTDIR): 

No extra environment shell script provided to configure!

targets_make: .../evm/.build/./libs/auto.mk install
make[1]: Entering directory '.../evm/libs'
.../evm/automk/default.sh targets_make install
targets_make: .../evm/.build/libs/evm/auto.mk install
make[2]: Entering directory '.../evm/libs/evm'
.../evm/automk/default.sh targets_make install
targets_make: .../evm/libs/evm/libevm.mk install
make[3]: Entering directory '.../evm/libs/evm'
install .../evm/.build/libs/evm/libevm.so /usr/local/lib/libevm.so
install .../evm/include/evm/libevm.h /usr/local/include/evm/libevm.h
make[3]: Leaving directory '.../evm/libs/evm'
make[2]: Leaving directory '.../evm/libs/evm'
make[1]: Leaving directory '.../evm/libs'
targets_make: .../evm/.build/./demos/auto.mk install
make[1]: Entering directory '.../evm/demos'
.../evm/automk/default.sh targets_make install
targets_make: .../evm/demos/hello1.mk install
install .../evm/.build/demos/hello1_evm /usr/local/bin/hello1_evm
...
make[1]: Leaving directory '.../evm/demos'
evm# 

evm# 
evm# exit
evm$ 

Clean:
------
evm$ 
evm$ make clean
.../evm/automk/default.sh targets_make clean
Sources absolute path (_SRCDIR_): .../evm
Build absolute path (_BUILDIR_): .../evm/.build
Target absolute installation prefix path (PREFIX): /usr/local
Additional absolute target installation path prefix (DESTDIR): 

No extra environment shell script provided to configure!

targets_make: .../evm/.build/./libs/auto.mk clean
make[1]: Entering directory '.../evm/libs'
.../evm/automk/default.sh targets_make clean
targets_make: .../evm/.build/libs/evm/auto.mk clean
make[2]: Entering directory '.../evm/libs/evm'
.../evm/automk/default.sh targets_make clean
targets_make: .../evm/libs/evm/libevm.mk clean
make[3]: Entering directory '.../evm/libs/evm'
...
make[3]: Leaving directory '.../evm/libs/evm'
make[2]: Leaving directory '.../evm/libs/evm'
make[1]: Leaving directory '.../evm/libs'
targets_make: .../evm/.build/./demos/auto.mk clean
make[1]: Entering directory '.../evm/demos'
.../evm/automk/default.sh targets_make clean
...
make[1]: Leaving directory '.../evm/demos'
evm$ 

If you want to remove all files not under version control and you are using git:
--------------------------------------------------------------------------------
$ git clean -d -f -x

Demos:
======
Programs included under "demos" directory demonstrate usage of the framework.

"hello1_evm" - Minimal framework utilization by sending HELLO message to itself
on every IDLE timer expiration. Sending messages to ourself may be accomplished
directly in framework without any system call (as in this demo).

"hello2_evm" - This demo shows sending message between two processes. The parent
process sends the first HELLO message to its child process. Every received
message in a child or parent process sets new timeout and another HELLO
message is sent back to the sender process after timeout expiration.

"hello3_evm" - This a threaded version of the second demo. The first
thread sends the first HELLO message to the second thread. Every received
message in any thread sets new timeout and another HELLO message is sent back
to the sender thread after timeout expiration.

"hello4_evm" - This is the one to many threaded example. The initial thread
spawns requested number of other threads and sets QUIT timer. Each other thread
sends initial HELLO message to the first thread. Every received message in any
thread sets a new IDLE timeout and another HELLO message is sent back to the
sender thread after timeout expiration.

"hello5_evm" - This is the one to many threaded example like "hello4". The
difference is, that initial thread posts a message to a topic, instead of sending
individual messages to each additional thread. Additional threads are being
subscribed to this topic at their creation.