NS3+Aqua-Sim-FG 仿真环境搭建+VSCODE调试

Aqua-Sim-FG是由吉林大学提出的第四代水声网络仿真系统：https://mp.weixin.qq.com/s/7GVC0LcR1R9MNG6uhSWtJg
github地址：https://github.com/JLU-smartocean/aqua-sim-fg

---

一、项目环境搭建过程

1.安装ubuntu22系统

2.配置ns3所需环境

CMD> apt install g++ python3 cmake ninja-build git ccache

3.下载并安装ns3.38

4.下载Aqua-Sim-FG模块，放入ns3主目录/src中

5.安装MATLAB环境

1）安装MATLAB R2023a Linux
2）安装MATLAB R2023a Linux Runtime

6.在ns3主目录/CMakeLists.txt文件中添加MATLAB相关头文件/库文件的路径

-------------ns3主目录/CMakeLists.txt-------------

# ----------------MATLAB 支持-------------
# 1) include_directories是指定头文件的路径，用于引入MATLAB RUNTIME的头文件到NS3代码中
include_directories(/MATLAB_Runtime_Path/R2023a/extern/include)

# 2) link_directories是指定库文件的路径
# MATLAB RUNTIME的库文件路径
link_directories(/MATLAB_Runtime_Path/R2023a/runtime/glnxa64)
# 指定自己编写的MATLAB库的路径
link_directories(${CMAKE_SOURCE_DIR}/src/aqua-sim-fg/model/lib)

# 3) link_libraries指定在库文件路径下，你实际要链接哪一个库
# 链接来自RUNTIME的库路径下的库文件 libmwmclmcrrt.so
link_libraries(mwmclmcrrt)
# 链接你自己编写的MATLAB库 libtest.so
link_libraries(test)   # 注意：去掉 lib 前缀和 .so 后缀
# ----------------MATLAB END-------------

7.安装python的cppyy包

CMD> python3 -m pip install --user cppyy==2.4.2

8.Building ns-3

CMD> ./ns3 clean
CMD> ./ns3 configure --enable-python-bindings
CMD> ./ns3 build

9.使用python3运行aqua-sim-fg/examples/下的aloha.py脚本

# 给python3声明import的包所在的路径
CMD> export PYTHONPATH=$PYTHONPATH:/ns_path/ns-3.38/build/bindings/python
# 声明动态库的路径，用于可执行程序在执行的时候进行动态库的链接（NS3库路径、MATLAB库路径）
CMD> export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/ns_path/ns-3.38/build/lib:/usr/local/MATLAB/MATLAB_Runtime/R2023a/runtime/glnxa64

# 运行脚本
CMD> python aloha.py

此时就可以看到终端有脚本仿真的输出：

---

二、踩坑记录

1.找不到某个库文件

在aloha.py启动时报错：

Exception: Failed to find libtestInitializemclGetMatrix_proxyarray_ref_set_numeric_mxInt32_proxy...（超长字符串）
Make sure its library directory is in LD_LIBRARY_PATH.

即找不到某一个库文件，但是这个字符串非常长，可能是错误的库文件名字，所以找不到

根本原因：

在 ns/__init__.py 中的 extract_library_include_dirs 函数。该函数的设计缺陷导致：

正则表达式过于宽泛：使用 re.findall(b"\x00(lib.*?.%b)" 在二进制文件中匹配模式，但会匹配到非库文件名

解决方法：

在 extract_library_include_dirs 函数中加一句代码过滤掉明显错误的非库文件名：

def extract_library_include_dirs(library_name: str, prefix: str) -> list:    	 ...
    # Now find these libraries and add a few include paths for them
    for linked_library in map(lambda x: x.decode("utf-8"), linked_libs):
    
        # -------（新加代码）跳过明显无效的"库名" - 添加过滤逻辑
        if len(linked_library) > 50 or "proxy" in linked_library.lower():
            print(f"跳过无效的库名: {linked_library}")
            continue
		# -------------------------------------------------
		
        # Skip ns-3 modules
        if "libns3" in linked_library:
            continue  
    ...

2.文件名冲突

aqua-sim-fg/model/文件夹下面有wave-helper.h/cpp文件，ns3原本的wave/helper/文件夹下面也有wave-helper.h/cpp文件文件：

导致在配置--enable-examples并进行build的时候报错
解决方法是把aqua-sim-fg/model/文件夹的wave-helper.h/cpp文件改个名字：如aqua-sim-wave-helper.h

---

三、VSCODE调试

因为这涉及到一个python+cpp的联合debug问题，所以需要启动两个调试器分别对python和c++代码进行debug。

实际上我们跑项目脚本时启动的是一个python进程，所以python的调试器启动方式是launch，c++的调试器启动方式是attach。

VSCODE中有一个Python C++ Debugger插件，可以让我们更方便的进行两种语言的联合debug

下载插件后，编写launch.json文件如下：

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "ns3-debug-python/cpp",
            "type": "pythoncpp",
            "request": "launch",
            "pythonLaunchName": "Python Launch",
            "cppAttachName": "C++ Attach",
        },
        {
            "name": "Python Launch",
            "type": "debugpy",
            "request": "launch",
            "program": "${workspaceFolder}/scratch/pythonScript/${fileBasename}",
            "cwd": "${fileDirname}", //程序的执行路径，当有打印输出文件的时候需要考虑修改
            "preLaunchTask": "ns3-build",
            "env":{
                "LD_LIBRARY_PATH": "${workspaceFolder}/build/lib/:/ns_path/ns-3.38/build/lib:/usr/local/MATLAB/MATLAB_Runtime/R2023a/runtime/glnxa64"
            },
        },
        {
            "name": "C++ Attach",
            "type": "cppdbg",
            "request": "attach",
            "processId": "",
            "MIMode": "gdb"
        }
    ],
}