TC3 SourceControl EN US - Beckhoff Automation · Title: TC3_SourceControl_EN_US Created Date:...

Manual

Source Control

TwinCAT 3

1.02015-06-22

VersionDate

Table of Contents

Table of Contents1 Foreword .................................................................................................................................................... 4

1.1 Notes on the documentation............................................................................................................. 41.2 Safety instructions ............................................................................................................................ 5

2 Integration of the Source Control Management ..................................................................................... 62.1 Project Files ...................................................................................................................................... 62.2 Project settings ................................................................................................................................. 62.3 Best Practice..................................................................................................................................... 9

3 Configuration of the source control client............................................................................................ 113.1 Selection of the Compare Tool ....................................................................................................... 12

4 TwinCAT Project Compare .................................................................................................................... 134.1 Configuration of the TcProjectCompare ......................................................................................... 134.2 Independent use of Project Compare ............................................................................................ 144.3 Merge of TwinCAT PLC Projects.................................................................................................... 16

Source Control 3Version 1.0

Foreword

1 Foreword

1.1 Notes on the documentationThis description is only intended for the use of trained specialists in control and automation engineering whoare familiar with the applicable national standards.It is essential that the following notes and explanations are followed when installing and commissioningthese components.

The responsible staff must ensure that the application or use of the products described satisfy all therequirements for safety, including all the relevant laws, regulations, guidelines and standards.

DisclaimerThe documentation has been prepared with care. The products described are, however, constantly underdevelopment.For that reason the documentation is not in every case checked for consistency with performance data,standards or other characteristics.In the event that it contains technical or editorial errors, we retain the right to make alterations at any timeand without warning.No claims for the modification of products that have already been supplied may be made on the basis of thedata, diagrams and descriptions in this documentation.

TrademarksBeckhoff®, TwinCAT®, EtherCAT®, Safety over EtherCAT®, TwinSAFE®, XFC®and XTS® are registeredtrademarks of and licensed by Beckhoff Automation GmbH.Other designations used in this publication may be trademarks whose use by third parties for their ownpurposes could violate the rights of the owners.

Patent PendingThe EtherCAT Technology is covered, including but not limited to the following patent applications andpatents:EP1590927, EP1789857, DE102004044764, DE102007017835with corresponding applications or registrations in various other countries.

The TwinCAT Technology is covered, including but not limited to the following patent applications andpatents:EP0851348, US6167425 with corresponding applications or registrations in various other countries.

EtherCAT® is registered trademark and patented technology, licensed by Beckhoff Automation GmbH,Germany

Copyright© Beckhoff Automation GmbH & Co. KG, Germany.The reproduction, distribution and utilization of this document as well as the communication of its contents toothers without express authorization are prohibited.Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of apatent, utility model or design.

Source Control4 Version 1.0

Foreword

1.2 Safety instructions

Safety regulationsPlease note the following safety instructions and explanations!Product-specific safety instructions can be found on following pages or in the areas mounting, wiring,commissioning etc.

Exclusion of liabilityAll the components are supplied in particular hardware and software configurations appropriate for theapplication. Modifications to hardware or software configurations other than those described in thedocumentation are not permitted, and nullify the liability of Beckhoff Automation GmbH & Co. KG.

Personnel qualificationThis description is only intended for trained specialists in control, automation and drive engineering who arefamiliar with the applicable national standards.

Description of symbolsIn this documentation the following symbols are used with an accompanying safety instruction or note. Thesafety instructions must be read carefully and followed without fail!

DANGER

Serious risk of injury!Failure to follow the safety instructions associated with this symbol directly endangers thelife and health of persons.

WARNING

Risk of injury!Failure to follow the safety instructions associated with this symbol endangers the life andhealth of persons.

CAUTION

Personal injuries!Failure to follow the safety instructions associated with this symbol can lead to injuries topersons.

Attention

Damage to the environment or devicesFailure to follow the instructions associated with this symbol can lead to damage to the en-vironment or equipment.

Note

Tip or pointerThis symbol indicates information that contributes to better understanding.


Integration of the Source Control Management

2 Integration of the Source Control ManagementTwinCAT 3 uses the Visual Studio Framework as basis of the workbench. One of the advantages of thisconcept is the simple access to the large selection of programming functions in Visual Studio.

Accordingly, TwinCAT also profits from the Source Control Management in Visual Studio.

This section describes how you can use this feature in TwinCAT 3.

2.1 Project FilesSo that a TwinCAT project is compatible with Source Control Management systems and supports work inteams, it is stored in several files. The following file extensions exist in the TwinCAT project:

File extension Source Con-trol Manage-ment

Merging permissible Description

*.tsproj yes yes, use TwinCAT ProjectCompare

TwinCAT project file

*.plcproj yes yes, use TwinCAT ProjectCompare

TwinCAT PLC project file

*.tmc yes not permissible for PLCprojects

TwinCAT module class (description file for aTcCom module)

*.tpy no - This file serves only for compatibility withprograms from other vendors.

*.xti yes yes, use TwinCAT ProjectCompare

In case of multiple file support, parts of theTwinCAT project file are stored with thisextension.

*.TcTTO yes yes, use TwinCAT ProjectCompare

PLC task object

*.TcPOU yes yes, use TwinCAT ProjectCompare

PLC program organizational unit (POU)

*.TcDUT yes yes, use TwinCAT ProjectCompare

PLC data type

*.TcGVL yes yes, use TwinCAT ProjectCompare

PLC Global Variable List

*.TcVis yes Not currently supported PLC visualization*.TcVMO yes Not currently supported PLC visualization manager*.TcGTLO yes yes, use TwinCAT Project

ComparePLC Global Texts List

NOTE! The description of the process image of a TcCom module is stored in the *.tmc file. If this isto be available directly after the checkout (fetching) of a project, even if the project had notpreviously been translated on one’s own computer, then the TMC file must be fetched with it (andthus checked in with the project beforehand). The TMC file is automatically re-generated aftertranslating a PLC project. It is therefore NOT merged for PLC projects and from TwinCAT 3.1 version4018 also no longer needs to be under Source Control administration!

NOTE! Manual merging of the files of a TwinCAT project is not generally recommended. TheTwinCAT Compare Tool should be always used for this!

2.2 Project settingsSo that a TwinCAT project that is managed using a source code management system can be processed in ateam as independently as possible, various settings can be set. These are described below.



Independent Project FileIt is possible in TwinCAT to save individual sub-projects, NC axes or IO devices explicitly in separate files.These files then contain all the parameters, etc. of the respective TwinCAT object, so that the completeproject file does not have to be “checked out” when making changes to this object. The links of a PLCproject, for example, are thus no longer stored in the TwinCAT project file, but in the corresponding XTI fileof the PLC project.

So that this function can be used in TwinCAT it must be “globally” enabled once. This is done via theTwinCAT – XAE Environment – File settings category in the TwinCAT engineering environment options.

The “Enable multiple files” option enables the use of this function for new projects. The options below itdefine the elements in a new project for which this function is switched on by default.

NOTE! Changes to these options only become effective after restarting the developmentenvironment!

Use of Independent Project Files in a projectIf this option is not activated by default for a TwinCAT object, this can be done and also reset using the“Independent Project File” option in the context menu of the TwinCAT Object.



Objects that are saved as Independent Project Files are marked in the TwinCAT tree with the aid of anoverlay icon in the form of a small floppy disk. A black floppy disk indicates that there are no unsavedchanges yet for this object, whereas this is the case with a red floppy disk.



Keep unrestored LinksUnless set differently, TwinCAT tries to avoid unnecessary loads on the project repository by no longerstoring information that is no longer required. In association with this, TwinCAT also checks whether links arestill valid. Any invalid links found are automatically deleted. This mechanism is obstructive when mergingprojects, since only the code and the links can be merged, but the updated process image is only availableafter recompiling the code that has now been merged. It is thus possible for the link information to be newerthan the process image and the automatic optimization function would delete all links to the new variables inthe process image. With the option “Keep unrestored links”, the link information marked for deletion isretained and automatically restored as soon as the variables show up in the process image.

2.3 Best PracticeThe following points should be borne in mind when using TwinCAT 3.1 in co-operation with Source ControlSystems:

• Both the TwinCAT project tree view and the PLC project tree view contain TwinCAT objects whoseinformation is stored in separate files (i.e. not directly in the respective project file). These elements aremarked by a small floppy disk in the tree icon. Their contents therefore cannot be accessed in the caseof merging the respective project file (files with the extensions *.tsproj and *.plcproj). It is therefore onlypossible, for example, to add a POU to a PLC project, but the changes inside a POU cannot be



accessed. The background to this is that the Source Control Clients do not “look inside” the files thatthey check out for merging and then also automatically load all the dependencies listed inside themfrom the Source Control System.

• If a merge conflict is detected when checking in a project file, a “get latest version” of the project shouldbe carried out before or at the latest after the merging of this file so that all “new” dependencies arealso present on the local system after merging.

Example:◦ User A and user B have the same software revision (revision 1). User A adds an element to

the PLC project and checks in the change (change in the PlcProj file and addition of a TcPoufile leads to revision 2)

◦ User B changes the contents of the plcProj file and wishes to check in this change. A conflictoccurs. User B still has revision 1 and now wishes to check in a revision 3. On merging, user Btakes over the change made by user A and checks in this change.

◦ A build will now fail, since user A also added the TcPou file. In order to rectify this, user B mustexecute a “Get Latest Version”. This can take place before or after checking in the change. Bychecking in a file a “GetLatest” is implicitly done on this file. This then leads to a conflict.

• Since TwinCAT objects in the project files are clearly identified with a GUID, it is always necessary toconfirm the deletion of an object with a “checkin”. For this reason the deletion of an object and thecreation of a new object with the same name and the same contents is always a change!

• Some objects in the TwinCAT tree require that they are also loaded in the background in order todisplay them in the tree. Thus all methods, actions, etc. of a POU are also stored in it. For this reason itis a good idea to close a project in TwinCAT first before fetching it again from the Source ControlSystem.


Configuration of the source control client

3 Configuration of the source control clientSelection of the Source Control Client

1. select Tools -> Options menu in the Microsoft Visual Studio Shell

ð The dialogue window shows all the settings for the Microsoft Visual Studio Shell environment.2. Select “Source control”

Further settings may be required depending on the selected Source Control Management System. Thisensures that Project Compare is called for comparing TwinCAT projects. These settings are generatedautomatically by TwinCAT Project Compare for clients of the Visual Studio Team Foundation Server and theAnkhSVN client for subversion.


Configuration of the source control client

3.1 Selection of the Compare ToolFollowing the selection of the Source Control Client to be used in the project, the client must also beconfigured so that the TwinCAT Project Compare Tool is used to compare and merge TwinCAT files. Theconfiguration of the individual clients can significantly differ.

Whereas clients such as TFS or PlasticsSCM allow different Compare Tools to be defined for the varioustypes of file, there are also clients that only permit a general Compare Tool to be set (e.g. AnkhSVN).Beyond that, Source Control Systems such as GIT also allow a distinction to be made between local (projectsettings) and global settings.

For the two Source Control Clients most frequently used with TwinCAT (TFS and AnkhSVN), the CompareTool can be automatically configured from the TwinCAT Project Compare Tool (see the section entitledConfiguration of the TcProjectCompare).

Transfer parameters of the TwinCAT Project Compare ToolsSince not all special features of the various clients can be dealt with here, the transfer parameters of theTwinCAT Project Compare Tools are briefly described below:

Compare (Compare/Diff):

C:\TwinCAT\3.1\Components\TcProjectCompare\TcProjectCompare.exe <destinationfile> <sourcefile> /sc

Example (PlasticsSCM): C:\TwinCAT\3.1\Components\TcProjectCompare\TcProjectCompare.exe"@destinationfile" "@sourcefile" /sc

Merge:

C:\TwinCAT\3.1\Components\TcProjectCompare\TcProjectCompare.exe /dl "destinationsymbolic" /dr“sourcesymbolic" <destinationfile> <sourcefile> <output> /sc

Example (PlasticsSCM): C:\TwinCAT\3.1\Components\TcProjectCompare\TcProjectCompare.exe /dl"@destinationsymbolic" /dr "@sourcesymbolic" "@destinationfile" "@sourcefile" "@output" /sc

Since some clients only allow the use of a general compare/merge tool for all file extensions, the TwinCATCompare Tool also offers the option to define further compare tools for special file extensions. It is thuspossible to refer to further compare/merge tools for non-TwinCAT files. (see Configure User Tools option ofthe TwinCAT Project Compare Tool)


TwinCAT Project Compare

4 TwinCAT Project CompareTwinCAT Project Compare is an independent application that compares TwinCAT projects. The tool can becalled automatically from the TwinCAT development environment if the Source Control Client iscorrespondingly configured. Further information on the configuration of Source Control Management clientscan be found under Configuration of Project Compare [} 13].

4.1 Configuration of the TcProjectCompareIn order to call the TwinCAT Project Compare Tool from the TwinCAT development environment, theselected Source Control Plugins must be configured accordingly in Visual Studio.

NOTE! These settings are generated automatically by TwinCAT Project Compare for clients of theMicrosoft Team Foundation Server and the AnkhSVN client for subversion.

Setup of TwinCAT Project Compare as the standard tool for “Compare and Merge” functions forsubversion AnkhSVN or Microsoft Team Foundation Server Clients:

1. open TwinCAT Compare2. select the Tools -> “Configure User Tools...” menu

3. in the following dialogue, select a standard tool “Merge”. This is used for all areas outside of the PLC(e.g. for the comparison of configurations for tasks).

4. Click on “Export configuration”



5. If the required Source Control Plugin has already been selected in Visual Studio Shell, you can exportthe configuration for this plugin if you are using a Microsoft Team Foundation Server or an AnkhSVNClient.

4.2 Independent use of Project CompareAfter starting TwinCAT Project Compare, the following dialogue appears:

With this dialogue you can select the two TwinCAT projects that are to be compared. The right-hand projectis the original project, the left-hand project is the project to be compared.



In order to display the changes in a TwinCAT object (e.g. a POU), open the comparison for this element witha double click.



4.3 Merge of TwinCAT PLC ProjectsIf more than one developer is working on the same PLC project, conflicts may arise when “checking in/committing” the changes. For example, parallel POUs can be added/edited by more than one developer ofthe PLC project. These conflicts must be solved if a consistent project is to be created. This procedure ofcombining changes is called merging.

Attention

The “automerge” function (automatic merging) of Source Control Clients canlead to the loss of PLC objects (POUs, GVL, etc.)!

• Deactivate automatic merging of Source Control Clients

• TwinCAT Project Compare must be configured as a merge tool (see Configuration ofthe TcProjectCompare [} 13])

In case of conflicts when checking in the PLC project, the following dialogue appears in the TSF Client:

To solve these problems



1. Select the option “Merge Changes In Merge Tool”2. After merging a PLC project (file extension *.PLCproj), request all files that were added to the PLC

project with “get latest version”.


TC3 SourceControl EN US - Beckhoff Automation · Title: TC3_SourceControl_EN_US Created Date:...

Documents

Transcript of TC3 SourceControl EN US - Beckhoff Automation · Title: TC3_SourceControl_EN_US Created Date:...