# 安装集成开发工具
mdev 是一套 MXCHIP 开发的集成开发工具包,它用于管理基于 MXOS 软件开发的完整流程。它是一个跨平台工具,支持 Windows, Linux 和 macOS,主要功能包括:
- MXOS 应用组件依赖管理:导入,更新,同步
- 检测硬件平台,自动下载和安装编译工具链
- 安装和调用构建系统,完成应用程序的编译,下载和调试
本文档包含 mdev 的安装和使用方法。
注意:在脚本示例中,使用的格式: ➜ <当前目录和git信息><命令>
, '......' 表示省略了部分信息输出。
#mdev的安装
#安装依赖:Python3 和 Git
#安装 python3, pip3
mdev 是一个 Python 3 脚本,所以您需要在系统中安装Python 3 (不支持 Python 2)。 注意: Python 3 的可执行文件目录需要添加到系统的PATH环境变量中。
参考:https://www.python.org (opens new window) 进行安装,在安装Python 3时,同时确保 pip3 也同时安装,pip3用于下载和安装python3 脚本。
在macOS上可以直接使用 brew install python3
在Linux上可以直接使用 sudo apt-get install python3
在终端上输入python3
命令来验证Python是否正确安装:
➜ ~ python3 --version
Python 3.9.10
➜ ~ pip3 --version
pip 22.0.4 from /opt/homebrew/lib/python3.9/site-packages/pip (python 3.9)
#安装 git
mdev 使用 git 对代码的版本进行管理。参考 https://git-scm.com (opens new window) 安装Git,支持版本 1.9.5 及以上,建议使用最新版本。
注意: Git 的可执行文件目录需要添加到系统的PATH环境变量中。
在终端上输入git --version
命令来验证是否正确安装:
➜ ~ git --version
git version 2.33.1
#安装 mdev
执行 pip3 install mdev
命令来安装 mdev:
➜ ~ pip3 install mdev
Collecting mdev
Downloading mdev-0.1.7-py3-none-any.whl (30 kB)
Requirement already satisfied: rich in /opt/homebrew/lib/python3.9/site-packages (from mdev) (12.0.0)
......
Requirement already satisfied: smmap=3.0.1 in /opt/homebrew/lib/python3.9/site-packages (from gitdb=4.0.1->GitPython->mdev) (5.0.0)
Installing collected packages: mdev
Successfully installed mdev-0.1.7
执行 mdev --version
查看当前安装的 mdev 版本,确认mdev正确安装。
➜ ~ mdev --version
0.1.7
mdev 安装完成后,可以通过pip3 install --upgrade mdev
命令来升级 mdev 的版本。
#mdev 的使用
#写在前面
mdev 对代码管理的基本工作流程:
- 新建或者导入一个项目,并为它创建一个 Git 版本库。在新建项目时,会在项目中自动附带一个 名叫 "mxos" 的标准组件,该组件提供了所有和硬件平台的BSP和核心API接口。
- 使用 Git 添加额外的组件代码,作为 Git sub-module 添加到当前项目进行管理或者手动添加 .component 文件,使组件成为 mxos 标准组件,使用mdev来进行版本管理。
- 编译,下载和调试应用程序代码。
- 同步组件版本,并且将应用程序同步到远程仓库。
mdev 使用 Git 作为代码版本管理工具,因此开发者可以直接使用 Git 命令管理代码,具体方法请参考Git的相关文档,本文不再赘述。同时 mdev 提供了一些特有的组件管理方式,与 mxos 应用开发结合更加紧密也更加易于使用。
小窍门: 使用mdev --help
可以列出所有 mdev 所支持的指令,特定某一个指令的帮助可以使用mdev <command>--help
。
mdev 包含 5 个子命令分别是
- new:创建一个新的 MXOS 项目。
- import:从远程代码仓库导入 MXOS 项目 和 内置的所有组件。
- deploy:根据项目中的组件描述文件,从远程代码仓库中获取组件代码。
sync:根据组件的当前 Git 提交版本状态,更新项目中的组件描述文件。
- build:编译和下载目标应用
注意:使用 mdev 工具获取MXOS SDK及相关组件,需先获得庆科授权,请联系:sales@mxchip.com。
#组件 和 MXOS 标准组件
独立于项目版本库,由单独的 Git 版本库管理的代码称为组件。组件提供一些通用的协议实现,功能包,扩展功能等,是 MXOS 项目不可缺少的重要组成部分。这些组件使用独立代码仓库进行管理,因此可以被不同的MXOS项目所引用。
通常可以用 Git submodule 的方式去管理这些组件。也可以将这些组件定义成 MXOS 标准组件,使用 mdev 来进行版本管理。用 mdev 导入项目时,可以递归导入这些MXOS标准组件。
创建 MXOS 标准组件的方法是:在组件的上级目录创建以<comp_folder>.component
为后缀的文件(comp_folder是组件文件夹的路径),并且在文件中保存依赖组件的Git链接信息。这些文件我们称之为组件描述文件。上层代码库通过组件描述文件跟踪组件的改动。
如在 xbtdemo 项目中,xmesh是一个独立的组件,有单独的 Git 仓库,xmesh.component 文件是组件描述文件,使得 xmesh 成为 MXOS标准组件。项目中还包含了 xtask,xuart,xbt等组件。
➜ xbtdemo git:(at-dev) ls
CMakeLists.txt lib_cJSON.component xmesh
README.md lib_light_ctl_driver xmesh.component
ReleaseNote.md lib_light_ctl_driver.component xtask
at-app mxos xtask.component
build mxos.component xuart
demos vbs9010 xuart.component
docs xbt
lib_cJSON xbt.component
组件描述文件文件内容格式是:<Git remte link or local directory>#<commit id or branch>, 例如
- module目录下的某一个git提交:
module/#3dffc01b8b202904c6dcdd7bcaf3d42d781afba2
- git remote是 https://code.aliyun.com/mxos/module.git 的 master 分支,导入时,总是获取该分支的最新提交:
https://code.aliyun.com/mxos/module.git#master
创建完组件描述文件文件后,只需要填写<Git remte link or local directory>部分,<commit id or branch>可以使用 mdev sync
命令来根据组件代码库当前状态自动生成。
#创建和导入项目
mdev 可以创建和导入基于 mxos 的软件项目。
#创建一个新项目:mdev new
每当你创建一个新项目,mdev 自动导入最新的 mxos sdk,并且提供 main 函数入口。
接下来让我们在 mxos-program
来创建一个新的项目 (命名为helloworld
):
➜ mxos-program mdev new helloworld
Creating a new MXOS program at path '/Users/william/Develop/mxos-program/helloworld'.
Downloading mxos and adding it to the project.
This may take a long time, please be patient, you can have a cup fo tea
Fetching /Users/william/Develop/mxos-program/helloworld/mxos/MXOS/security/TLS/mbedtls/mbedtls-2.16.5 ...
这个命令创建了一个新的目录"helloworld",初始化了一个新的版本库并且在项目中导入了一个最新版本的mxos-os依赖。我们也可以自己创建一个新目录,并且在该目录下执行 mdev new .
即可。
接下来,我们可以尝试编译一下:
➜ mxos-program cd helloworld
➜ helloworld git:(master) ✗ mdev build -c helloworld emc3080
......
[90/91] Generating image ...
╭───────────────────── Congratulation! ─────────────────────╮
│ │
│ ███████╗██╗ ██╗ ██████╗ ██████╗███████╗███████╗███████╗ │
│ ██╔════╝██║ ██║██╔════╝██╔════╝██╔════╝██╔════╝██╔════╝ │
│ ███████╗██║ ██║██║ ██║ █████╗ ███████╗███████╗ │
│ ╚════██║██║ ██║██║ ██║ ██╔══╝ ╚════██║╚════██║ │
│ ███████║╚██████╔╝╚██████╗╚██████╗███████╗███████║███████║ │
│ ╚══════╝ ╚═════╝ ╚═════╝ ╚═════╝╚══════╝╚══════╝╚══════╝ │
│ │
╰───────────────────────────────────────────────────────────╯
在编译过程中,mdev 会自动检测当前编译的硬件平台,并且下载相应的依赖代码和工具。
#导入一个现有的项目
#使用 mdev import
在日常开发中,通常基于一个已有的示例项目进行修改和拓展。所以从导入一个已有的项目开始。
你可以使用 mdev import
命令从一个版本仓库克隆一个项目到本地,并且递归部署项目中包含所有 MXOS 标准组件:
➜ mxos-program mdev import https://code.aliyun.com/mxos/demos.git
Cloning MXOS program 'demos'
Resolving program component dependencies ...
This may take a long time, please be patient, you can have a cup fo tea
Fetching demos/lib_http_parser ...
Fetching demos/lib_http_short_connection ...
Fetching demos/lib_http_file_download ...
Fetching demos/lib_amebad_bt ...
Fetching demos/lib_breeze ...
Fetching demos/mxos ...
Fetching demos/lib_jsmn ...
Fetching demos/lib_cJSON ...
Fetching demos/lib_fog_v3_ota ...
Fetching demos/mxos/MXOS/security/TLS/mbedtls/mbedtls-2.16.5 ...
Components List
╭───────────────────────────┬───────────────────────────────────────────────┬────────╮
│ Library │ Path │ Commit │
├───────────────────────────┼───────────────────────────────────────────────┼────────┤
│ lib_amebad_bt │ lib_amebad_bt │ a8c583 │
│ lib_breeze │ lib_breeze │ 12d35e │
│ lib_cJSON │ lib_cJSON │ 2e538f │
│ lib_fog_v3_ota │ lib_fog_v3_ota │ 1ab36c │
│ lib_http_file_download │ lib_http_file_download │ 06c33f │
│ lib_http_parser │ lib_http_parser │ bab714 │
│ lib_http_short_connection │ lib_http_short_connection │ ad17cd │
│ lib_jsmn │ lib_jsmn │ b2db68 │
│ mbedtls-2.16.5 │ mxos/MXOS/security/TLS/mbedtls/mbedtls-2.16.5 │ cfddab │
│ mxos │ mxos │ 3dffc0 │
╰───────────────────────────┴───────────────────────────────────────────────┴────────╯
说明:如果你在"import"命令中不指定完整的路径,mdev 会自动加上默认的路径前缀 (https://code.aliyun.com/mxos) 。例如,mdev import demos
和命令mdev import https://code.aliyun.com/mxos/demos.git
等价。
Note:demos 是什么?
demos 中包含了各单元的示例代码,如::外设,wifi无线,wifi_uart串口透传,安全算法,net网络通信,http通信等。另外,与云平台对接,蓝牙通讯等功能,MXCHIP 均提供了单独的项目供开发者导入。
#使用 git clone 和 mdev deploy
如果我们直接用 git clone
从代码库中获得代码,代码中所需要的 MXOS 组件可以在项目目录下通过 mdev deploy
获取,如:
➜ mxos-program git clone https://code.aliyun.com/mxos/demos.git
正克隆到 'demos'...
remote: Enumerating objects: 2216, done.
remote: Counting objects: 100% (2216/2216), done.
remote: Total 2216 (delta 879), reused 2191 (delta 879)
接收对象中: 100% (2216/2216), 13.23 MiB | 8.49 MiB/s, 完成.
处理 delta 中: 100% (879/879), 完成.
➜ mxos-program cd demos
➜ demos git:(master) mdev deploy
Checking out all componets to revisions specified in .component files. Resolving any unresolved componets.
This may take a long time, please be patient, you can have a cup fo tea
......
#添加和移除组件
我们可以用 Git 的sub-module 模块管理组件,这里,我们介绍怎么使用 mdev 来管理组件。
mdev 在管理组件时,添加和删除功能不等同于git
版本管理软件的内置功能,而是针对 MXOS 项目的特点进行了改造。参考:MXOS 标准组件 (opens new window)。
将新的组件添加到项目中,需要同时编写组件描述文件(
.component
)。移除一个组件也不仅仅是删除这个组件目录,而且要同时删除组件描述文件。
组件产生新的Git Commit后,使用
mdev sync
命令更新组件描述文件中的版本记录。从而更新上层项目或者组件。➜ demos git:(master) ✗ mdev sync
Synchronizing all .component files to revision of it's componet. Components List
╭───────────────────────────┬───────────────────────────────────────────────┬────────╮
│ Library │ Path │ Commit │
├───────────────────────────┼───────────────────────────────────────────────┼────────┤
│ lib_amebad_bt │ lib_amebad_bt │ a8c583 │
│ lib_breeze │ lib_breeze │ 12d35e │
│ lib_cJSON │ lib_cJSON │ 2e538f │
│ lib_fog_v3_ota │ lib_fog_v3_ota │ 1ab36c │
│ lib_http_file_download │ lib_http_file_download │ 06c33f │
│ lib_http_parser │ lib_http_parser │ bab714 │
│ lib_http_short_connection │ lib_http_short_connection │ ad17cd │
│ lib_jsmn │ lib_jsmn │ b2db68 │
│ mbedtls-2.16.5 │ mxos/MXOS/security/TLS/mbedtls/mbedtls-2.16.5 │ cfddab │
│ mxos │ mxos │ 3dffc0 │
╰───────────────────────────┴───────────────────────────────────────────────┴────────╯
#编译,下载
#MXOS 项目编译
mdev build 使得开发者可以方便地和 MXOS 项目中的 Cmake + Ninja 构建系统对接,从而完成项目的编译和下载。当然,对于高阶开发者或者某些特定应用,开发者也可以直接使用 Cmake 和 Ninja 命令来实现项目的编译下载。
mdev build 的命令格式是:
➜ demos git:(master) ✗ mdev build --help
Usage: mdev build [OPTIONS] PROJECT MODULE
Build a MXOS project.
Arguments:
PROJECT : Path to the MXOS project
MODULE : Module name
Example:
$ mdev build demos/helloworld emc3080
Options:
-f, --flash [APP|ALL|None] Download firmware to flash after built.
-c, --clean Rebuild the project.
-h, --help Show this message and exit.
其中
PROJECT:是目标应用的路径,路径中必须包含
CMakeLists.txt
文件MODULE:硬件型号,选择应用程序运行时使用的BSP,命令所支持的型号就是在 mxos/module 下子目录的名称
选项:
-c, --clean:在每次编译之前都清楚上次编译产生的输出文件,重新编译
-f, --flash [APP|ALL|None]:编译完成后,下载到硬件的选项
- APP:只下载应用程序
- ALL:清空和下载完整的 Flash 镜像
- None(默认):不下载
编译生成的可执行文件,ELF文件,内存使用和链接数据可以在
build/<PROJECT>/
目录下找到。
编译示例:
基于EMC3080模组,编译demos项目中helloworld目录下的应用程序。
➜ mxos-program cd demos
➜ demos git:(master) ✗ mdev build -c demos/helloworld emc3080基于EMB1016模组,编译xbtdemo项目中at-app/ble目录下的应用程序,编译完成后下载应用固件到模组Flash中。
➜ mxos-program cd xbtdemo ➜ xbtdemo git:(at-dev) mdev build -c at-app/ble emb1016 -f APP
#编译静态库
每一个组件在编译时都会先生成静态库,在进行连接。静态库可以在 build 文件夹中找到,也可以在组件的 CMakelists.txt 中增加自定义目标,自动地将生成的静态库拷贝出来,下面是一个名为xmesh的组件,自动将生成的静态库拷贝到上层目录的例子:
add_custom_target(xmesh.${HOST_ARCH}.${TOOLCHAIN_TYPE}.release.a ALL
COMMAND${CMAKE_COMMAND} -E copy
${CMAKE_CURRENT_BINARY_DIR}/lib${MXOS_CURRENT_LIBRARY}.a
${CMAKE_CURRENT_SOURCE_DIR}/../xmesh.${HOST_ARCH}.${TOOLCHAIN_TYPE}.release.a
DEPENDS ${APP_TARGET}.elf
VERBATIM
)
最后在上层目录生成类似于:xmesh.Cortex-M33.GCC.release.a 这样的静态库。
#进阶编译
mdev build 实际上使用的是 Cmake 和 Ninja 命令来实现构建的,所以我们可以直接使用 cmake 和 ninja 命令,这对于高级应用提供了更多的灵活性和扩展能力。针对 mdev build -c at-app/ble emb1016 -f APP
命令所对应的 cmake 和 ninja命令如下:
cmake -B build/at-app/ble-emb1016 -GNinja -DAPP=at-app/ble -DMODULE=emb1016 -DFLASH=APP -DMXOS_ENV=/Users/snowyang/.mdev -DCMAKE_MAKE_PROGRAM=/Users/snowyang/.mdev/build/ninja
其中,MXOS_ENV 是mdev自动下载的各种工具的根目录,cmake在这个目录下查找gcc编译器,CMAKE_MAKE_PROGRAM 是make工具名称,这里是 mdev 下载的 ninja。
ninja -C build/at-app/ble-emb1016
#推送改动
通过 git commit
命令提交对代码的改动,并且使用 git push
命令推送带远程代码库。
需要注意的是,如果一个组件向代码仓库提交了新的改动后,如果需要将改动同步给其他开发者,那么需要使用 mdev sync
命令来使得组件描述文件(.component文件)中的连接保持同步,然后更新项目的代码库版本。否则其他开发者调用mdev import
或者mdev deploy
命令导入的项目中仍然会使用旧的组件代码库。