OMNeT++代码迁移指南：从3.x到4.0

第一章：3.x版本后的改变

概述

因为C++ API、NED、ini和msg文件的改变，为OMNeT++ 3.x版本写的仿真模型是不能直接在OMNeT++ 4.0及其以后的版本中使用的。本文档描述了如何将一个3.x的模型转化为可以在OMNeT++ 4.0下运行的模型。

在进行代码迁移之前，你应该已经熟悉OMNeT++ 3.x和4.0版本。我们建议在继续之前看看4.0中的示例仿真文件。

NED文件

NED语言被大幅度的修改，并增加了大量的语法。还包括有扩展的一系列新概念：继承，模块和信道接口，内部类型，双向连接，package结构，元信息（属性）等等。下面列表显示了从3.x版本以来的重大改变。

• 大括号的引入，用于下列地方：模块和信道的定义（去掉了endsimple, endmodule, endnetwork, endchannel等关键字）中；子模块中；连接中的链路参数中。
• gate定义以及参数的语法从Pascal风格变成了C风格。
• 在参数中，numeric参数类型已经被取消，根据上下文需要将其转化为int或者double。
• const关键字被移除，而引入了一个volatile新的关键字；在3.x中不限制的参数值是不确定的，而在4.0中则为常数0。
• display字符串变成了属性，采用@display(...)的语法。
• input关键字被移除，而对于参数的提示可以采用属性来做：@prompt(...)。
• 引入了一个新的参数属性@unit(...)，用来表示物理单位。对于有单位的参数，在ini和NED文件中的值必须要给出相同或者可以转换的单位，否则将会报告一个错误。
• 取消了ref关键字，因为现在参数总是通过引用来传递的。
• 取消了ancestor 关键字。
• 复合模块中的gatesizes节重命名为gates。
• Conditional 参数以及gatesize 节已经不再被支持。大多数情况下，它们可以被?:操作符所替代。
• connections nocheck改为了connections allowunconnected。
• connection 的for循环语法也得到了改变。
• 现在已没有布尔类型和long/double类型之间的隐式转换。
• import声明已经改为一个完整的package定义
• 现在可以在网络中直接使用子模块，而不需要像在3.x中必须创建一个复合模块并单独声明成网络。

报文消息文件（msg）

field属性的语法改成了和NED文件一致。

初始值设置文件（ini）

• [Cmdenv], [Tkenv], [Parameters], [Partitioning] 和 [OutVectors] 节已经不存在了，其内容需要拷贝到[General]节下。
• [Cmdenv] 和[Tkenv]中的配置选项需要分别加上cmdenv- 和tkenv-前缀。
• [Run 1], [Run 2], ... 节已经不能使用，而应该被转换为命名配置如[Config First], [Config Second]等。注意，现在运行个数已经不再依赖于配置文件，而是参考迭代次数。
• cmdenv-express-mode选项（[Cmdenv]下的express-mode选项）将默认值从false改为了true。
• [Tkenv]节中的大部分选项已经被移除，除了下面几个：tkenv-default-run, tkenv-image-path, tkenv-plugin-path。
• tkenv-default-run选项（[Tkenv]中为default-run）已经和迭代次数联系了起来，所以现在只有和新的tkenv-default-section一起才有意义。
• 现在有一个新的cmdenv-interactive选项，默认为false，这使得Cmdenv将不会读取标准输入，在缺少参数值的时候中止。在3.x版本中，默认的行为是从标准输入中读取值。
• preload-ned-files选项已经被移除，因为在4.0中，NED文件是通过从NED路径中的文件夹中加载得到的（NED路径是一个包含了文件夹列表的字符串，可以从NEDPATH环境变量、命令行选项或者是ini文件中的ned-path选项来获得。对于只有一个目录的仿真模型，默认值"."应该已经足够了）。
• 在3.0版本中，network选项被指代为一个从preload-ned-files选项中的文件获取的NED类型。在4.0版本中，则指代一个在ned-path选项中的可用的目录。在许多情况下，network选项并不需要修改。
• **.somepar.use-default=true语法应该改为**.somepar=default。**=default没有必要写出来，因为这是默认的行为。
• 还有一些配置选项被重命名或者改变。更多细节的问题，请参看src/envir/ChangeLog和其他ChangeLog文件。

项目配置文件（Makefile）

makefile的生产和make过程已经被重写过。现在，一个opp_makemake --deep可以替代非常复杂的makefile系统，这可以用于多目录的仿真模型，如INET框架。使用opp_makemake -h来获取更多的信息。

makefile生成器可以生成三种类型的makefile：

• 本地的（默认）：只有当前目录下的源文件会被包含，而忽略子目录。在单目录的工程中推荐这种方法。
• 递归的（--recurse）：包含当前目录中的源文件，并且在所有子目录中被调用。这将在所有的子目录下生成Makefile文件。
• 更深的（--deep）：这在多目录项目中是适用的。所有目录下的源文件将被递归收集出来。只会在根目录下生成一个Makefile文件。项目的包含路径也会被自动查找。可以通过 -X 选项排除某些目录。

C++代码（cc/h）

下面是从3.x版本以来API的主要变化。请参看include/ChangeLog来获取更详细的信息。

• omnetpp/include中的几个头文件被重命名。（这不会影响到仿真模型，因为在仿真模型中只需要包含<omnetpp.h>。）
• cObject 重命名为cOwnedObject, cPolymorphic 重命名为cObject，引入了cNamedObject 。不同类中的几个方法已经改变。检查ChangeLog文件来获取详细信息。
• 为几乎所有的getter方法增加了get动词。
• <omnetpp.h>提供了C99的整数类型和limit宏，即使是系统中不存在<stdint.h>。
• simtime_t现在不是double而是SimTime类型（64位）。
• 增加了simtime的兼容模式：如果需要的话，仿真内核可以编译成simtime_t=double。为了达到这点，可以加入USE_DOUBLE_SIMTIME定义（在CFLAGS中增加-DUSE_DOUBLE_SIMTIME标志）。
• 增加了inout门。对于这种类型的门，gate("gatename")是不会工作的，使用gate("gatename$i") 或者gate("gatename$o")。
• Channel变为了“一等公民”：和cModule一样有着同样的基类cComponet，参与了initialize()/finish() 协议，等等。
• 引入了cComponent作为cModule 和cChannel的基类。有些新方法需要在这里提及：isModule(), getNedTypeName()。
• cBasicChannel 重命名为 cDatarateChannel，增加了cIdealChannel 使得信息可以在传递的时候不经过任何延时和修改。
• 异常处理机制的变化：现在所有的异常都是继承于std::exception（如cException 是std::exception的子类）。同时，现在异常是通过值抛出而不是指针。
• cOutVector：从cOutVector及其下层中去除了用处不大的tuple=2支持，并且为元信息增加了一些方法：setEnum(), setUnit(), setType(), setInterpolationMode(), setMin(), setMax()等。
• 和cDisplayString相关的许多改动。参加include/ChangeLog。
• cQueue：去掉了head()/tail()，增加back()/front()（在最后插入，在前面删除）。因为head()/tail()的变化，insertBefore()/insertAfter()的迭代指示符也变化了。另外，指示递增递减顺序的布尔变量也被删除了。
• cMessage 变化：cMessage 中的长度，比特错误标志和封装信息被从cMessage移到了cPacket类中（从cMessage继承）。所有的网络分包（帧、数据报等）现在都是从cPacket继承，而不是直接从cMessage中继承。
• 一个新的cPacketQueue 被引入用来保存cPacket及其子类。
• 全局的findXXX(const char *name)函数被改为static cXXX::find(const char *name);方法。（受影响的：findLink(), findFunction, findEnum, findChannelType, findNetworkType(), findModuleType()）
• cEnvir. cSimulation::runNumber()中的Run number handling已经移除。同样从cEnvir 回调函数的参数列表中移除。

环境变量

OMNETPP_BITMAP_PATH环境变量被更名成OMNETPP_IMAGE_PATH。OMNeT++将会在运行时进行检查，如果发现老的环境变量将会打印出警告信息。

命令行选项

• 当指定ini文件的时候-f是可选的。
• -r现在用来指代运行次数，而不是在ini文件中的命名配置。一般的，-r只有和-c（选择运行配置）选项一起的时候才有意义。
• 使用-h来获取仿真执行使的帮助信息（或者是opp_run -h获取OMNeT++的信息）。
• 需要更多的信息可以使用opp_run -h或者可执行仿真文件的-h选项。

第二章：迁移工具

代码迁移的过程有些步骤可以自动化执行。OMNeT++ 4提供了几个实用的命令行工具来帮助代码迁移。这些工具可以在OMNeT++ 4的migrate目录下找到。

migratened

这个工具递归的对当前目录下的.ned文件进行迁移。此工具将完成下面的过程：

• 将所有的simple, module, network, channel类型定义改成新的大括号样式。
• 将参数定义改变成新样式。
• 删除const修饰词，并为非const参数定义增加volatile修饰词。
• 为了安全原因，此工具将numeric 参数变为double。以后必须手工检查，如果int已经足够的话。
• 将所有的submodule 声明变为新的大括号语法。

migratemsg

这个工具递归的对当前目录下的.msg文件进行迁移。此工具将完成下面的过程：

• 将所有的属性改为新格式。

migrateini

这个工具递归的对当前目录下的.ini文件进行迁移。此工具将完成下面的过程：

• 将[Parameters], [Cmdenv], [Tkenv], [OutVectors] 和[Partitioning]移动到了[General]中。
• 将多个出现的[General]节合并成一个。
• [Cmdenv] 和[Tkenv]中的没有加上前缀的条目加上cmdenv- 和tkenv-。
• 将[Run 1], [Run 2]等重命名为[Config config1], [Config config2]等。
• 重命名已经更改的配置选项。
• 将**.use-default 更改为**=default。

migratecpp

这个工具递归的对当前目录下的.cc和.h文件进行迁移。此工具将完成下面的过程：

• 将代码中明确标志的已经更改的类重命名。
• 删除废弃的宏（如Define_Module_Members()）。
• 在所有可能需要进一步修改和检查的地方打印警告语句。

opp_makemake

这个工具并不是一个迁移工具，但是可以使用其来生成新的Makefile文件。旧的Makefile文件不能够使用。

第三章：如何迁移代码

我们推荐你按照几个步骤来迁移你的仿真模型：

。尽快的工作在4.0版本下：

。使用自动迁移脚本

。对自己的模型进行手工迁移，并使用尽可能少的新特性

。检查你的模型是否能够工作，并看是否可以产生和旧模型一样的结果（精确的或者是统计上的）

。使用OMNeT++ 4版本的新特性对其进行改进。

使仿真模型可以工作

。前提条件：已经安装好了OMNeT++ 4.0并可以工作，同时熟悉IDE的操作。

。为你的仿真模型做个备份。因为可能在迁移成功之前需要做多次尝试。

。切换到你的仿真模型目录，并运行在<omnetpp>/migrate中的所有脚本文件。

$ cd MyModel
$ ../omnetpp-4.0/migrate/migratened
$ ../omnetpp-4.0/migrate/migrateini
$ ../omnetpp-4.0/migrate/migratemsg
$ ../omnetpp-4.0/migrate/migratecpp | tee migratecpp.out
这些脚本文件将转换NED、ini、msg和C++文件到4.0的格式。结果可能还需要进一步处理，因为不是所有的东西都可以自动转换的。脚本将在你可能需要手工修改的地方打印警告信息，所以请注意这些打印信息。特别的，migratecpp脚本将打印一系列的注意、警告和提示，认真的读读它们。

。如果你的仿真模型是基于INET框架的，则首先要安装新的INET，然后执行在INET下的子目录migrate/中的脚本。这将会根据INET框架的变化而对源代码进行修改。

$cd MyModel
$ ../INET/migrate/migratened
$ ../INET/migrate/migrateini
$ ../INET/migrate/migratemsg
$ ../INET/migrate/migratecpp | tee migratecpp.out

。接下里的工作你可以在命令行中完成，也可以在OMNeT++ IDE中完成。我们推荐使用后者。为了使用IDE，需要为仿真模型创建一个工程。在菜单中选择File | New | OMNeT?+?+ Project...，将会出现一个向导。在第一页中，取消“Use default location”的复选并选择你的仿真模型目录，然后继续其他向导页，并在最后点击Finish，你应该可以看到在左边的“Project Explorer”有了一个新工程，其中包含了你的工程中的文件。如果发生了错误，选择工程并点击DEL。IDE将会询问是否将文件也从磁盘中删除，选择“No”。然后可以重新开始工程的创建。

。如果你的工程是依赖于INET或者其他工程，你可以设置一个依赖于INET的工程。为了做到这点，INET工程必须已经导入和打开，然后在你的工程中打开Properties对话框（选择工程，右键点击，从上下文菜单中选择Properties ），然后在Project References页中检查INET。这将使得INET中的NED类型可以用你的工程，同时将INET的目录加入到了C++的头文件路径。确保INET框架编译成了库（静态或者动态），这样你的工程才可以链接到INET。可以通过检查INET工程的Project Properties对话框中的C/C++ Build / Makemake页面。

。OMNeT++ 4.0版本中的NED有着和Java类似的包系统。如果你的模型在不同的子目录中包含有NED文件，这些子目录意味着包，NED文件需要包声明同时增加了import。这在IDE中可以自动完成。创建或者打开你的工程，从菜单中选择Navigate | Clean up NED files...。选择你的工程并点击OK。IDE将修复所有的包声明并导入你的NED文件。

你可能需要一个package.ned文件来定义你的根包——这将在后面一节进行讨论。

。对NED文件进行修订。包括：

。修订volatile型的参数，看看它们是否必须要使用volatile

在原来模型中如果没有指定为const的参数，volatile的限定符可能会出现的比较多。如果一个参数在仿真过程中是不变的，则可以将volatile限定符安全的删除。所以作为一个规则，只有在仿真期间被读取的变量才有可能需要设置为volatile，而不是在初始化阶段。如果只是在initialize()函数中使用了的参数，则可以将volatile限定符去掉。

检查为double的参数是否可以为int。

3.x版本中的numeric参数类型将会被自动转换为double类型，但是你可以根据需要将其改为int。确保你同步修改了相应的C++源代码。

。somepar = input; 将变成somepar; ——你可能需要删除它们。

提示：

NED文件中已经不支持使用input关键字，但是你可以在ini文件中设置**.somepar=ask来达到同样的效果。

。移除多余的网络定义

3.x风格的网络定义实际上是一个网路的复合模块。在4.0版本中，一个复合模块可以直接被定义成为一个网络，而不需要多余的步骤。举个例子，3.x版本中的网络定义：

network cqn : CQN
endmodule
将会被自动迁移脚本转换为继承的形式：
network cqn extends CQN {
}

实际上，你可以完全删除这个定义。可以使用network关键字来改变CQN的模块定义（如network CQN {...}），同时在ini文件中将network=cqn替换为network=CQN。

。"like"模块类型应该被改为接口，而且真实的类型声明应该相像。

例如，你有一个子模块：

app:< appType> like App;

App应该变为一个模块接口（一般习惯上在前面加上一个“I”）：

moduleinterface IApp {
gates:
input in;
output out;
}

而具体的类型则应该根据IApp来修改：

simple BurstyApp like IApp { ... }
simple AnotherApp like IApp { ... }

。编译你的仿真模型（右键点击你的工程，从上下文菜单中选择“Build”，或者是关闭所有的其他工程然后按下Ctrl+B）。常见的编译错误以及解决方法：

。不能将SimTime 转换为double（"Cannot convert SimTime to double"）

simtime_t现在是一个基于int64的SimTime类，而不是double。无论在什么地方一个simtime_t被赋值成double类型，考虑将其修改为simtime_t。新的SimTime没有提供和double之间的隐式转换，因为这可能会造成C++的歧义性错误。检查迁移工具的输出，其中给出了应该修改变量的一些提示。

提示：

如果需要的话，使用SIMTIME_DBL(t) 来将一个 simtime_t类型转换为double类型。在printf函数中，使用"%s"和SIMTIME_STR(t)。使用这些宏而不是SimTime 方法的好处是可以编译成-DUSE_DOUBLE_SIMTIME的兼容模式。

提示：

如果你使用了很多double类型的时间变量，同时西王佐一个快速的移植，有一个比较不是很干净的方法，那就是在CFLAGS中指定-DUSE_DOUBLE_SIMTIME，从而使得其保持原来的行为。需要注意的是，如果这样做的话，需要使用此标志重编译所有的OMNeT++库。我们建议如果可能的话尽量使用新的SimTime 类型。

。"No such method setBitLength/getBitLength/encapsulate/decapsulate"
长度和封装属性已经移到了cPacket中，这是cMessage的一个子类。你可能需要将.msg文件中的message关键字改为packet关键字，从而使得生成的类使用cPacket作为基类。

message ABCPacket {...} ==> packet ABCPacket {...}

在handleMessage()和其他函数中，将cMessage*指针指向cPacket*：

cPacket *pkt = check_and_cast<cPacket *>(msg);

。"Cannot open file csimul.h" (or any other header)

只有<omnetpp.h>是公共的API。其他的OMNeT++头文件不应该被直接引用，因为有可能在以后的版本中改名或者删除。

。"sendDirect() does not take 3 (or 4) arguments"
sendDirect()函数已经更改。过去此函数经常接受延时作为第二个参数。现在此函数有两个变种，一个没有时延参数（所以，如果你的仿真模型中是0.0，则可以直接删除），而另外一个则接受传播时延和传输持续时间。如果你准备使用第二种的话，你可能需要在目标模块中接收门的initialize()方法中调用setDeliverOnReceptionStart(true)。

。运行你的仿真模型。常见的错误和解决方法：

。"Cannot convert unit 'none' to 'seconds'"

物理类型必须写在表达式中，所以需要将5改为5s，而将exponential(1)改为exponential(1s)。

。"Cannot convert unit 'none' to 'bps'"

现在的信道数据率参数有了物理单位：bps(bit/sec)，这个单位必须写出，支持的单位包括Kbps, Mbps, Gbps。

。"No such module type 'X'"

如果你的模型动态创建了模块，模块类型必须使用一个完全的属性名称进行查找（如"some.package.X"）。

第四章：使用新的OMNeT++特性

NED文件

。增加了默认的图标。

现在可以为模块类型指定一个显示字符串（包含有一个图标等）。在运行的时候默认值将和子模块的显示字符串合并成一个有效的显示字符串。为了能够使的模块显示默认图标，你可以将子模块中的"i="标签移动到相应的简单模块类型。结果将项下面一样：

simple Node {
@display("i=block/fork");
...
}
module Net {
submodules:
node1 : Node {
@display("p=240,100"); // note: "i" tag moved out
}
...
}

。在ini文件中定义的值可以放入对应的NED文件中作为默认值。如果你的ini文件中包含有大量的很少改动的参数，可以将其移动到NED文件中。使用下面的语法：

int somepar = default(42);

。使用@unit为你的模块参数指定物理单位。这将强迫参数中包含有物理单位。

volatile double interArrivalTime @unit(s);

。使用模块的继承。

如果你有几个模块都有着同样的行为，而仅仅只是参数不同。你可以使用模块继承。举个例子：

simple Router {
int ports;
}
simple Router8 extends Router { // still uses the "Router" C++ class!
ports = 8;
}
simple Router16 extends Router {
ports = 16;
}
注意：C++类将从记模块中继承，也就是说，所有的三个模块都将使用C++的Router类，即使在C++中有 Router8 类等。为了能够将C++类也替换，需要增加一个@class属性：

simple AdvancedRouter extends Router {
@class(AdvancedRouter); // makes it use the "AdvancedRouter" C++ class
}
继承同样可以用于将几个复合模块的相同部分组合成一个基类型。继承类可以继续增加子模块和连接，以及新的参数和门。

。使用inout门来表示双向连接。一对单向连接可以通过一个双向连接替代。下面是语法示例：

gates:
inout port;
...
connections:
node1.port <--> node2.port;

。使用内类型

如果只是在本地使用一个类型，则可以将其转化为内类型。这在信道定义的时候特别有用。

module Network {
types:
channel Ethernet extends ned.DatarateChannel {
datarate = 100Mbps;
};
...
connections:
node1.port <--> Ethernet<--> node2.port;
...
}

。如果你准备将你的模型给别人的话，为你的NED文件定义一个包的根目录。这可以避免和其他模型的名字冲突。为了做到这点，放一个