Cbridge setup

CBridge Setup

In order to compile and execute C/C++ actions, a C compiler toolchain has to be installed on the machine, where the Bridge executable (Windows: cBridge.exe / Unix: cBridge) runs.
Typically this is the local machine on which expecco runs, but it may be any other machine in your reachable network.
The CPU architecture and or operating system may be (and often is) different from the CPU which executes expecco, therefore the C-code is compiled on the target machine (i.e. not cross-compiled).

C-Compiler Toolchain Installation

Windows + Borland Compiler (32bit)

The compiler is a bit outdated, but still free and useful.
However, it only supports 32bit programs. Thus, it cannot be used if you need access to 64bit dlls.
(on the other hand, if you need to interact with a 32bit dll to communicate with some hardware device, you'll must use a 32bit cBridge).

We recommend to install the toolchain at its default installation path (typically "C:\borland"). Then, the provided cc-compile script for borland can be used unchanged.

Windows + MINGW Compiler (32 or 64bit)

The mingw toolchain is based on the gcc compiler. This is recommended and preferred over borland.

Windows + Microsoft Visual C / Visual Studio

There is no need to install the full Visual Studio IDE. Only the C-compiler, linker and libraries are required. Thus, you can untoggle all additional optional packages during the installation.

Check for the "cl" command (being in your PATH) or find and remember the path to it (typically somewhere under "c:\Program Files\Microsoft\...").

Unix / Linux

Install whatever packages are required; check if the "cc" command is found along your PATH (before starting expecco), or alternatively, remember the path to the "cc" command.

Regardless of which compiler you use, please remember the installation path. You will need it later unless the compiler is found along your PATH.

Quick Check if it Already Works

We provide a number of setups for common installations. In many situations, this will already be correct for your setup.

To check, create a new elementary-bridgedC action, and run it. (the initial tree which is created with examples also contains a simple C action).

If you get a green OK result, you're already done. If not, your setup needs to be adjusted.

Read the chapter at the end of this page on step-by-step setup verification.

The Compile Script

For compilation, the cBridge program calls a batch/shell script, which is responsible for compilation of the C-code to a DLL/shared object file. This script may need to be edited. We recommend, that you navigate to the folder where the cBridge executable is located, take one of the existing scripts as template, make a copy under a new name, and then edit this copy to suit your needs.

Take one of the existing scripts which uses the same compiler (borland/mingw/visualC).

In the editor, check the PATH setting, and edit it as appropriate, finally save it.

Back in expecco, go to the cBridge settings under the external-script settings, and change the CC-script setting there ("Extras" - "Settings" - "Execution" - "External Script Interpreters" - "CBridge").

Shutdown any already running bridge ("Extras" - "Debugging" - "Shutdown all Bridge Connections")

Go back to the C-action and repeat the quick check.

Eventually, you should see a green OK result.

Special Additional Libraries

It may be required that your C-code needs additional shared libraries to be linked against your code. The easiest is to add those libraries and corresponding command line options to the CC-script's compiler call command. The details depend on the compiler used. You may need to do a "cc --help", "cl/help" or similar, to figure out which command line options are required.

Remote C-Bridges

You can run any number of cBridges on any machine within your network, and execute C-actions there. For this, the following setup steps are to be performed:

• copy the cbridge executable and its support files to a new folder on the target machine; the files are found below the expecco installation folder
  (eg. "c:\Program Files\exept\expecco") in "packages\bridgeFramework\cBridge\cLibrary".

The easiest way is to copy the whole folder. Make sure that the copied folder matches the target machine's architecture (i.e. if the target is a Linux machine, you must obviously copy the files from a Linux installation, and same so for Windows machines).

• on the remote machine, make sure that the cBridge is running; either by executing a remote command from inside your expecco suite, or by adding the cBridge startup to a cron tab (Unix/Linux) or the service list or autoexec.bat (Windows).

As a test, start it manually with: "cBridge --port 8856", and connect to it from expecco (change the settings ("Extras" - "Settings" - "Execution" - "External Script Interpreters" - "CBridge") to connect to an already running cBridge at that port).

• if in doubt, start the cBridge with a "--help" option.

SSL Connection to the Remote CBridge

You'll need certificate and key files to be generated on the expecco side and manually transport them to the target system.

Details to be documented...

Step-by-Step Problem Finding/Fixing

Ensure that the cBridge executable is present and can be executed

• goto the expecco installation folder (typically somewhere under "c:\Program Files\exept\expecco\"), and look for files named "cBridge.exe" or "cBridge32.exe" or "cBridge" (under Unix/Linux). It is typically found in a sub folder named "packages/expecco/bridgeFramework/cBridge".
• open a shell- or cmd window (and navigate there).
• type "cBridge --help" (with powershell: ".\cBridge --help")

if that fails (does not output some useful help text), make sure that it can be executed.
Maybe your security policy is too strict ot the installation is incomplete.

• start the bridge with "cBridge --log"

it should output some messages, the last being "... listening on port xxxx"

• if the cBridge is to run on a machine different from the one expecco is running on, make sure that the firewall allows for connections between the two machines (at the desired port nr)
• if required, use another port (i.e. run it with "cBridge --log --port <Nr>")

now we have a cBridge running, ready to accept connections from expecco at the given port nr.

• keep the shell/cmd window open; we will need it later (and also to see any diagnostic output)

Ensure that the cBridge is reachable from expecco

for this, we first try to connect to that already running bridge (instead of letting expecco start it itself)

• in expecco, open the settings and navigate to the cBridge settings:

"Extras" → "Settings" → "Execution" → "External Script Interpreters" → "CBridge"

• check the "Connect to already Running Bridge" box.

enter CBridge Host and Port as "localhost" and the above port number (default is 8855)

• close the settings dialog (without saving the settings for now, when asked)
• open a new project.
  The default project will contain a sample "Hello World" C-action, which can be used for the smoke test.
• in the expecco tree, find the "Simple Elementary Action (C)" (under the "Activities" group).
• run it

if the error states that no connection could be setup, check your security policy, firewall etc. and repeat

if the error states that the compilation failed, the bridge connection works, but the compilation script setup is wrong. Proceed.

Ensure that the compilation works

the cBridge needs a C-compiler for its operation; to verify,

• stop the manually started C-bridge (in the shell/cmd window) by pressing CTRL-C there
• depending on the C-compiler you intend to use, one of the "compile_xxx.bat" or "compile_xxx.sh" script files will be used. The task to be performed by these scripts is to compile a given C-file.
• check which compiler you installed and intent to use (MSVC, Mingw, gcc, clang or bcc), and look for a corresponding script file.
• check if the compiler is correctly installed (especially MSVC and MINGW sometimes make trouble here).

one particular problem with MSVC is when deinstalling and reinstalling another version. There seem to be leftover files and/or registry entries which may break the installation (this happend to one of our customers, and also to us when upgrading)

• Enter the compile-command ("cl", "cc", "gcc" or "clang") on a command line (cmd or shell)

check that you get an answer

try to compile a one-liner (eg. "main() { printf("hello\n"); }" and run it to see if it links correctly. Run it!

• check if the bridge's cc script file works by running "cBridge --log --ccScript <scriptfilename> --testCompile"

if required, make a copy of one of the script files (the one you think is best to start with) and fix any path inside. If required, add echo statements to show what is going on. Keep the original script and create a new one.

under Windows: in the script, the PATH to the compiler is typically searched and set; for example by calling the vcvarsall.bat script which is provided by microsoft. If required, change the line which calls this (you can also add this batch-call to your autoexec.bat and remove the line from the script). In any case: at the end, the "cl" command should be found along your path.

• the --testCompile will generate a piece of code which outputs "here is foo"; i.e. on your system (we use mingw), the command is "cBridge --log --ccScript compile_windows_mingw.bat" --testCompile", and the output is "here is foo" - "void pointer size: 8", followed by the usual "listening on port" message.

Change the Settings in expecco

• open the cBridge settings again
• uncheck the "Connect to already running bridge" box
• enter the name of the compile script into the "CC-script" field (possibly the name of the new script)
• shutdown any already running bridge
• try executing the expecco-C action again
• if you get a green outcome, save your expecco settings.

---

Copyright © 2014-2024 eXept Software AG