PLCnext CLI 模板

本文适用于 PLCnext CLI 版本 22.0.0 LTS。

如果您使用 C++ 对 PLCnext Control 设备进行编程，您可能使用了随 PLCnext CLI 一起安装的代码模板。

在 Visual Studio 和 Eclipse 中，您必须在使用 PLCnext 项目向导（随 PLCnext IDE 扩展安装）创建新项目时选择要使用的项目模板。

使用 PLCnext CLI 在命令行上生成新的 C++ 项目时，还必须指定项目模板。

三个默认的项目模板是：

  project              The project is a template for user programs.
                       They are managed by the PLM (Program Library Manager).

  acfproject           The acfproject is a template for component based platform development.
                       The resulting component will be managed by the ACF
                       (Application Component Framework).

  consumablelibrary    The consumable library is a template, that creates a library
	                   which can be used by other projects.

执行plcncli new可以看到以上信息命令。有关这些类型项目的更多信息，请访问 PLCnext 信息中心：

ACF 和 PLM 的界定
创建和使用共享库

本文介绍如何激活和使用随 PLCnext CLI 安装的其他项目模板，以及如何创建和使用您自己的项目模板。

但首先，让我们看看 PLCnext CLI 模板系统是如何工作的。

PLCnext CLI 模板系统

PLCnext CLI 包含一个名为 TemplateLocations 的默认设置，这告诉它在哪里可以找到代码模板。您可以使用以下命令查看此设置的值：

user@machine:~$ plcncli get setting TemplateLocations

{
  "setting": {
    "TemplateLocations": "./Templates/Templates.xml"
  }
}

xml文件的路径是相对于plcncli 安装路径。

如果您浏览到 ./Templates 目录，你会看到 Templates.xml 文件，以及一些子目录。

列出 Templates.xml 的内容文件...

user@machine:~/plcncli/Templates$ cat Templates.xml

<?xml version="1.0" encoding="utf-8"?>
<Templates xmlns="http://www.phoenixcontact.com/schema/clitemplates">
  <Include type="Template">ProjectTemplate/TemplateDescription.xml</Include>
  <Include type="Template">ProgramTemplate/TemplateDescription.xml</Include>
  <Include type="Format">ProjectTemplate/FormatTemplates.xml</Include>
  <Include type="Template">ComponentTemplate/TemplateDescription.xml</Include>
  <Include type="Template">BaseTemplates/BaseTemplateDescription.xml</Include>
  <Include type="Template">BaseTemplates/CodeTemplateDescription.xml</Include>
  <Include type="Fields">BaseTemplates/FieldTemplates.xml</Include>
  <Include type="Types">BaseTemplates/TypeTemplates.xml</Include>
  <Include type="Format">BaseTemplates/FormatTemplates.xml</Include>
  <Include type="Template">AcfProjectTemplate/TemplateDescription.xml</Include>
  <Include type="Template">BaseProjectTemplate/TemplateDescription.xml</Include>
  <Include type="Template">AcfComponentTemplate/TemplateDescription.xml</Include>
  <Include type="Template">BaseComponentTemplate/TemplateDescription.xml</Include>
  <Include type="Template">ConsumableLibraryTemplate/TemplateDescription.xml</Include>
</Templates>

...你可以看到有对 TemplateDescription.xml 的引用 Templates下面的目录中的各种类型的文件目录。这些包含告诉 PLCnext CLI 在使用该模板时要做什么的指令。

上面显示的模板描述文件实现了您已经熟悉的三个默认项目模板。

如何激活其他模板

PLCnext CLI默认安装了一个“隐藏”项目模板，默认不可用：

  minimumproject    This is the same as acfproject, but without the capability to create 
	                Port variables in the Global Data Space.

我们可以通过添加 MinimalAcfTemplates.xml 使这个模板可用于 PLCnext CLI 文件 - 您可能已经在 Templates 中注意到了目录 - 到模板位置设置：

user@machine:~$ plcncli set setting TemplateLocations ./Templates/MinimalAcfTemplates.xml --add

新的 XML 文件现已添加到模板位置：

user@machine:~$ plcncli get setting TemplateLocations

{
  "setting": {
    "TemplateLocations": "./Templates/Templates.xml;./Templates/MinimalAcfTemplates.xml"
  }
}

...当 plcncli new 命令执行，minimumproject 现在出现在选项列表中。此模板现在可用于从命令行创建新的 C++ 项目。

注意： 将项目模板添加到 PLCnext CLI 不会自动将项目模板添加到 Visual Studio 或 Eclipse 项目向导。

如何创建自己的 PLCnext CLI 模板

将使用一个简单的示例演示自定义 PLCnext CLI 模板的创建。将创建一个生成“Hello World！”的 PLCnext CLI 模板。 C++ 中的控制台应用程序。

程序如下：

为新的 PLCnext CLI 项目模板创建一个目录。

在 Linux 上：

user@machine:~/plcncli/Templates$ mkdir ExeTemplate && cd ExeTemplate

创建一个包含模板 C++ 代码的文件，该文件可用作此类每个新项目的起点。

user@machine:~/plcncli/Templates/ExeTemplate$ touch Main.cpp

本例中使用的 C++ 代码为：

#include 

int main() {
   std::cout << "Hello World!" << std::endl;
   return 0;
}

创建模板cmake源文件。

user@machine:~/plcncli/Templates/ExeTemplate$ touch CMakeLists.txt

本例使用的 CMake 代码为：

cmake_minimum_required(VERSION 3.13)

project($(name))

if(NOT CMAKE_BUILD_TYPE)
  set(CMAKE_BUILD_TYPE Release)
endif()

################# create target #######################################################

file(GLOB_RECURSE Headers CONFIGURE_DEPENDS src/*.h src/*.hpp src/*.hxx)
file(GLOB_RECURSE Sources CONFIGURE_DEPENDS src/*.cpp)
add_executable(${CMAKE_PROJECT_NAME} ${Headers} ${Sources})

#######################################################################################

################# set install directories #############################################

string(REGEX REPLACE "^.*\\(([0-9]+\.[0-9]+\.[0-9]+\.[0-9]+).*$" "\\1" _ARP_SHORT_DEVICE_VERSION ${ARP_DEVICE_VERSION})
set(BIN_INSTALL_DIR ${ARP_DEVICE}_${_ARP_SHORT_DEVICE_VERSION}/${CMAKE_BUILD_TYPE})

#######################################################################################

################# project include-paths ###############################################

target_include_directories(${CMAKE_PROJECT_NAME}
    PRIVATE
    $)

#######################################################################################

################# include arp cmake module path #######################################

list(INSERT CMAKE_MODULE_PATH 0 "${ARP_TOOLCHAIN_CMAKE_MODULE_PATH}")

#######################################################################################

################# set link options ####################################################
# WARNING: Without --no-undefined the linker will not check, whether all necessary    #
#          libraries are linked. When a library which is necessary is not linked,     #
#          the firmware will crash and there will be NO indication why it crashed.    #
#######################################################################################

target_link_options(${CMAKE_PROJECT_NAME} PRIVATE LINKER:--no-undefined)

#######################################################################################

################# add link targets ####################################################

find_package(ArpDevice REQUIRED)
find_package(ArpProgramming REQUIRED)

target_link_libraries(${CMAKE_PROJECT_NAME} PRIVATE ArpDevice ArpProgramming)

#######################################################################################

################# install #############################################################

install(TARGETS ${CMAKE_PROJECT_NAME} RUNTIME DESTINATION ${BIN_INSTALL_DIR})
unset(_ARP_SHORT_DEVICE_VERSION)

#######################################################################################

请注意，CMake 代码包含占位符 $(name) , 将替换为传递给 plcncli new 的项目名称命令。

可选：将README文件添加到新的模板目录中，也可以用于在从该模板创建的每个新项目中创建一个README文件。
创建一个 PLCnext CLI 项目配置文件。

该文件用于存储 PLCnext CLI 的项目配置信息，例如应为其构建项目的目标列表。

对于此示例，.proj 文件是从 ConsumableLibraryTemplate 复制的目录并编辑生成以下内容：
```
<?xml version="1.0" encoding="utf-8"?>
<ProjectSettings xmlns="http://www.phoenixcontact.com/schema/cliproject">
  <Type>exeproject</Type>
  <Version>0.1</Version>
  <Name>$(name)</Name>
</ProjectSettings>
```
Type 字段应包含该项目模板的唯一名称，该名称也将包含在下一步的模板描述文件中。

Name 字段包含占位符 $(name) ，在创建每个新项目的过程中会替换为项目名称。

创建模板描述文件。

对于此示例，TemplateDescription.xml 文件是从 ConsumableLibraryTemplate 复制的目录并编辑生成以下内容：

<?xml version="1.0" encoding="utf-8"?>
<TemplateDescription name="exeproject" isRoot="true" basedOn="baseproject" supportedFirmwareVersions="19.0.0.16199" requiredCliVersion="19.0.0.660" version="1.0" 
                     xmlns="http://www.phoenixcontact.com/schema/clitemplates" identifier="ProjectSettingsIdentifier">
  <File name="plcnext.proj" template=".proj"/>
  <File name="CMakeLists.txt" template="CMakeLists.txt"/>
  <File name="README.md" template="README.md"/>
  <File name="$(name)Main.cpp" template="Main.cpp" path="src"/>
  <Description>Create a new stand-alone executable project.</Description>
  <Example>
    <Arguments>
      <Argument name="name" value="MyExe"/>
    </Arguments>
    <Description>creates a new stand-alone executable project in the directory 'MyExe'</Description>
  </Example>
</TemplateDescription>

模板描述中的字段包括：

name="exeproject" :允许使用命令 plcncli new exeproject 从该模板创建项目 .
File name="A" template="B" path="C" ：根据指定的模板文件在新项目中的指定路径中创建一个文件。文件名还可以包含 $(name) 等占位符，在创建每个新项目期间将替换为项目名称。
Description 和 Example 字段，显示在plcncli的相关部分帮助系统。

创建一个新的模板文件，该文件将用于告诉 PLCnext CLI 我们的新模板。

对于此示例，MinimalAcfTemplates.xml Templates 中的文件目录被复制到一个名为 CustomTemplates.xml 的文件中，并且该文件被编辑以产生以下内容：
```
<?xml version="1.0" encoding="utf-8"?>
<Templates xmlns="http://www.phoenixcontact.com/schema/clitemplates">
         <Include type="Template">ExeTemplate/TemplateDescription.xml</Include>
</Templates>
```

使用 PLCnext CLI 注册自定义模板

user@machine:~$ plcncli set setting TemplateLocations ./Templates/CustomTemplates.xml --add

该路径是相对于 PLCnext CLI 安装目录的。

试试看！

以下 bash 命令列表演示了新模板的功能：

plcncli new                                   # The help text includes the new template and description
plcncli new exeproject --help                 # Displays the example showing how to use this template
plcncli new exeproject --name "HelloWorld"    # Creates a new project based on the template
cd HelloWorld
plcncli set target -n AXCF2152 -v 2022 --add  # Sets the build target
plcncli build                                 # Builds the project with the default template code
scp bin/AXCF2152_22.0.3.129/Release/HelloWorld [email protected]:~  # Copies the executable to the device
ssh [email protected]
./HelloWorld                                  # Runs the executable!

贡献

将来，计划对 Github 上的 PLCnext CLI 模板项目做出贡献。在此之前，您可以使用新模板的想法或您自己创建的模板示例来打开问题。

问题或意见？

在下方发表评论，或在 PLCnext 社区论坛中提问。

PLC模拟的痛苦回忆如何在 Visual Studio 中调试 C++ 组件和程序

工业技术