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.

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