# 安装集成开发工具
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命令导入的项目中仍然会使用旧的组件代码库。