CODESYS Forge

ERROR! The markdown supplied could not be parsed correctly. Did you forget to surround a code snippet with "~~~~"?

[[download url=https://forge.codesys.com/svn/tol,cforge,code/trunk/cforge.package]]
[[embed url=https://www.youtube.com/watch?v=SfEIKFUnEvU&]]

[[include ref=IndexMain]]

[TOC]

# Preface
CODESYS Forge (or short **cforge**) is a small tool which should help developers and users to use the services offered on CODESYS Forge.
**cforge** is basically written in C# but can be extended with IronPython scripts. As it makes use of IronPython and MS Scripting, you might have problems running it on anything else than Windows.

# Installation
**cforge** itself is packed as a CODESYS package. That leads to the most important prerequisite: CODESYS programming system has to be installed on your PC.
There are different ways of installing **cforge** to your PC.

## Prerequisits
To make full use of the cforge functionality, you need:

* [CODESYS](https://store.codesys.com/codesys.html)
* [CODESYS SVN](https://store.codesys.com/codesys-svn.html)
* [Tortoise SVN](https://tortoisesvn.net/downloads.html) (with installed commandline tools)

Make sure to install the command line tools to your PATH:

[[img src=tortoise.png height=250px]]

## Installation via CODESYS package
If you have no cforge installed before, just use the "cforge<...>.package" and let CODESYS do the installation:

### Download
Download the cforge package in your browser:
[current development cforge package](https://forge.codesys.com/tol/cforge/code/HEAD/tree/trunk/cforge.package?format=raw)
Please see also the tags code repository for "releases" of cforge tool.

### Install Package
Double click on the (or execute the) cforge package file and let CODESYS install the package.

### Register Protocol Handler
Now please go to your CODESYS installation folder. There should be a subfolder called "CFORGE". E.g.: 
    ` C:\Program Files (x86)\3S CODESYS\CODESYS\CFORGE`

Inside this folder, please execute the "Setup.bat".
    This will do 2 important things for the cforge tool:
    - Add this folder to your windows "path" environment variable (if not yet there)
    - Add some magic registry entries for the mechanism of the URL protocol handler, so that links starting with "cforge:" do work on your machine.
        But don't be afraid: it is that simple (in case, that you need it for some other cool tools) ;-)

~~~
[HKEY_CLASSES_ROOT\cforge]
@="URL:cforge Protocol"
"URL Protocol"=""

[HKEY_CLASSES_ROOT\cforge\shell]

[HKEY_CLASSES_ROOT\cforge\shell\open]

[HKEY_CLASSES_ROOT\cforge\shell\open\command]
@="\"C:\\Program Files (x86)\\3S CODESYS\\CODESYS\\CFORGE\\cforge.exe\" \"%1\""
~~~

### Register Explorer Commands
Currently not many commands for the Explorer Integration are available, yet. But they can already be
installed, using the Registry file Setup.reg.

Just have a look into it, and double click on it to install the menu if you like it.

## Installation/Update via cforge
This works, as long as cforge was already installed (and setup) to your current CODESYS installation.
Then, just use the INSTALL link at the top of the page.

# CODESYS Users
CODESYS users which have this package installed get an easy access to all their favorite packes, drivers and projects from CODESYS Forge.
The typical operations/commands they can use **cforge** for are:

## Package installation
Packages can be installed as easy as clicking on the cforge download button of a project. cforge registers an URL protocol handler in Windows, which handles URLs, starting with the protocol "cforge:".
By clicking on such a link, the corresponding software is downloaded and installed using cforge.

[Install cforge via cforge](cforge:install:https://forge.codesys.com/tol/cforge/code/HEAD/tree/trunk/cforge.package?format=raw)

When using **cforge** on the command line, you can use the `--install <package-url>` command to install a package. 

# Developers
cforge helps developers in several reoccuring tasks of maintaining their CODESYS software.

## Checkout
You can always use the standard mechanisms of the CODESYS SVN package to check your projects out. But with cforge you can easily checkout a folder, containing multiple libraries.

You will end up with a folder with projects, that are up to date and have the right connection to the SVN repository that you just checked out.

## Import / Commit
Again, you can use the standard mechanism of CODESYS SVN to commit your changes on your projects. But here cforge has several advantages:

* You can import or check in several projects and libraries at once
* cforge will also commit every project in binary form, containing the SVN connection settings to your repository
* cforge will commit a Markdown file, containing an export of the source code

~~~
MyProject/
MyLib/

(these files are generated)
MyProject.project
MyProject.md
MyLib.library
MyLib.md
~~~

## Release
You can also use cforge to automate your release process a bit. cforge can use the tagged projects to prepare compiled libraries, which have the released flag set.

So, a release with cforge can look like:

* Create a branch from current trunk
* Checkout this branch
* Enter the checkout directory and run "cforge release -r"
* Optionally also.run "cforge package package.manifest"
* Commit your changes with "cforge commit"
* Tag branch with Tortoise to "tags/vx.x.x.x/"

Doing the same w/o cforge would need a lot more manual interaction:

* Checkout every single project and library
* Set the release flag in all libraries
* Save all libraries as compiled library
* Update a package manifest
* Create a CODESYS package from the manifest
* Commit the sources with CODESYS SVN
* Commit the compiled libraries, packages and project files with an external SVN client

## Walkthrough

[[embed url=https://www.youtube.com/watch?v=UvH572rz1Ng]]
[[embed url=https://www.youtube.com/watch?v=6NzHBWH5I1c]]



# Misc
To be cleaned up later:

### Debug cforge
As it is a C# tool, just use Microsoft VisualStudio to run / attach to your local **cforge** instance.
There is a nice trick: just lay a file named "debug" (content does not matter) next to the **cforge.exe** and it will patiently wait when started (e.g. from the browser via a "cforge:" url), so that you have time to attach. Then just press Enter in the console (as it is mentioned there), and continue to debug.
Then you can even debug the IronPython scripts.