# Install mdev
Mdev is an integrated development kit developed by MXCHIP, which is used to manage the complete process of MXOS based software development. It is a cross platform tool that supports Windows, Linux and macOS. Its main functions include:
- MXOS application component dependency management: import, update, synchronization
- Detect the hardware platform, and automatically download and install the compilation tool chain
- Install and call the building system to complete the compilation, download and debugging of applications.
This document contains the installation and usage of mdev.
Note: In the following example, the format “➜<current directory and git information><command>“， '...' means that some information is omitted from the output.
#Installation of mdev
#Installation dependency: Python 3 and Git
#Install python3 and pip3
Mdev is a Python 3 script, so you need to install Python 3 in the system (Python 2 is not supported). Note: The executable file directory of Python 3 needs to be added to the PATH environment variable of the system.
Reference resources: https://www.python.org (opens new window) (opens new window). When installing Python 3, ensure that pip3 is also installed at the same time. Pip3 is used to download and install python 3 scripts.
- You can directly use brew install python3 on the macOS.
- You can directly use sudo apt get install python3 on Linux.
Enter the python3 command on the terminal to verify whether Python is installed correctly:
➜ ~ python3 --version Python 3.9.10 ➜ ~ pip3 --version pip 22.0.4 from /opt/homebrew/lib/python3.9/site-packages/pip (python 3.9)
#Install git
Mdev uses git to manage code versions. reference resources https://git-scm.com (opens new window) (opens new window) Install Git, which supports version 1.9.5 and above. It is recommended to use the latest version.
Note: The Git executable directory needs to be added to the PATH environment variable of the system.
Enter the git -- version command on the terminal to verify the correct installation:
➜ ~ git --version git version 2.33.1
#Install mdev
Execute pip3 install mdev to install 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<6,>=3.0.1 in /opt/homebrew/lib/python3.9/site-packages (from gitdb<5,>=4.0.1->GitPython->mdev) (5.0.0) Installing collected packages: mdev Successfully installed mdev-0.1.7
Execute mdev -- verify to view the currently installed version of mdev and confirm that mdev is installed correctly.
➜ ~ mdev --version 0.1.7
#Usage of mdev
#Write on the front
Basic workflow of code management in mdev:
- Create or import a project and create a Git version library for it. When a new project is created, a standard component named "mxos" will be automatically attached to the project, which provides BSP and core API interfaces for all hardware platforms.
- Use Git to add additional component code and add it to the current project as a Git sub module for management or manually add a. component file to make the component a mxos standard component. Use mdev for version management.
- Compile, download, and debug application code.
- Synchronize component versions and synchronize applications to remote repositories.
mdev uses Git as a code version management tool, so developers can directly use Git commands to manage code. For specific methods, please refer to Git's related documents, which will not be repeated in this article. At the same time, mdev provides some special component management methods, which are more closely integrated with mxos application development and easier to use.
Tip: Use mdev -- help to list all the instructions supported by mdev, and use mdev<command>-- help for specific instructions.
Mdev contains five subcommands:
- New: Create a new MXOS project.
- Import: Import MXOS projects and all built-in components from the remote code warehouse.
- Deploy: Get the component code from the remote code warehouse according to the component description file in the project.
- Sync: Update the component description file in the project according to the current Git submission version status of the component.
- Build: compile and download the target application
Note: To use the mdev tool to obtain the MXOS SDK and related components, you need to obtain the authorization of MXCHIP first. Please contact: sales@mxchip.com.
#Components and MXOS standard components
The code managed by a separate Git version library, independent of the project version library, is called a component. The component provides some common protocol implementations, function packages, extended functions, etc., and is an indispensable part of the MXOS project. These components are managed using an independent code repository, so they can be referenced by different MXOS projects.
These components can usually be managed by Git submodule. You can also define these components as MXOS standard components and use mdev for version management. When using mdev to import projects, you can recursively import these MXOS standard components.
The method to create MXOS standard components is: create the file with<comp_ folder>.componentas suffix in the parent directory(comp_folder is the path of the component folder), and the Git link information of the dependent components is saved in the file. These files are called component description files. The upper code base tracks component changes through component description files.
For example, in the xbtdemo project, xmesh is an independent component with a separate Git repository The component file is a component description file, making xmesh a MXOS standard component. The project also includes xtask, xuart, xbt and other components.
➜ 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
The content format of the component description file is:<Git remote link or local directory>#<commit id or branch>, for example
- Submit a git under the module directory:
module/# 3dffc01b8b202904c6dcdd7bcaf3d42d781afba2 - Git remote is https://code.aliyun.com/mxos/module.git (opens new window) The master branch of. When importing, always get the latest submission of this branch: https://code.aliyun.com/mxos/module.git#master (opens new window)
After creating the component description file, you only need to fill in the<Git remte link or local directory>section.<commit id or branch>can be automatically generated by using the mdev sync command according to the current state of the component code base.
#Create and import projects
Mdev can create and import mxos based software projects.
#Create a new project: mdev new
Whenever you create a new project, mdev automatically imports the latest mxos sdk and provides the main function entry.
Next, let's create a new project (named helloworld) in mxos program:
➜ 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 ...
This command creates a new directory "helloworld", initializes a new version library, and imports a new version of the mxos os dependency in the project. We can also create a new directory and execute mdev new .
Next, we can try to compile:
➜ mxos-program cd helloworld ➜ helloworld git:(master) ✗ mdev build -c helloworld emc3080 ...... [90/91] Generating image ... ╭───────────────────── Congratulation! ─────────────────────╮ │ │ │ ███████╗██╗ ██╗ ██████╗ ██████╗███████╗███████╗███████╗ │ │ ██╔════╝██║ ██║██╔════╝██╔════╝██╔════╝██╔════╝██╔════╝ │ │ ███████╗██║ ██║██║ ██║ █████╗ ███████╗███████╗ │ │ ╚════██║██║ ██║██║ ██║ ██╔══╝ ╚════██║╚════██║ │ │ ███████║╚██████╔╝╚██████╗╚██████╗███████╗███████║███████║ │ │ ╚══════╝ ╚═════╝ ╚═════╝ ╚═════╝╚══════╝╚══════╝╚══════╝ │ │ │ ╰───────────────────────────────────────────────────────────╯
During compilation, mdev will automatically detect the currently compiled hardware platform and download the corresponding dependent code and tools.
#Import an existing project
#Using mdev import
In daily development, it is usually modified and expanded based on an existing example project. So start by importing an existing project.
You can use the command dev import to clone a project from a version repository to the local, and the recursive deployment project contains all MXOS standard components:
➜ 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 │ ╰───────────────────────────┴───────────────────────────────────────────────┴────────╯
Note: If you do not specify a complete path in the "import" command, mdev will automatically add the default path prefix（ https://code.aliyun.com/mxos (opens new window) ) 。 For example, mdev import demos and the command mdev import https://code.aliyun.com/mxos/demos.git (opens new window) Equivalence.
Note: What is demos?
Demos contains sample codes of each unit, such as: peripherals, wifi wireless, wifi_ uart serial port transparent transmission, security algorithm, net network communication, http communication, etc. In addition, MXCHIP provides separate projects for developers to import such functions as cloud platform connection and Bluetooth communication.
#Use git clone and mdev deploy
If we directly use git clone to obtain code from the code base, MXOS components required in the code can be obtained through mdev deploy in the project directory, such as:
➜ 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
#Add and remove components
We can use Git's sub module module to manage components. Here, we introduce how to use mdev to manage components.
When managing components, mdev adds and deletes functions that are not equivalent to the built-in functions of git version management software, but are modified according to the characteristics of MXOS projects.
- To add a new component to the project, you need to write a component description file (
.component) at the same time. - To remove a component is not only to delete the component directory, but also to delete the component description file.
- After the component generates a new Git Commit, use the
mdev synccommand to update the version record in the component description file. To update the upper level project or component.
➜ 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 │
╰───────────────────────────┴───────────────────────────────────────────────┴────────╯ #Compile, download
#MXOS Project Compilation
Mdev build allows developers to easily interface with the Cmake+Ninja build system in the MXOS project, thus completing the compilation and download of the project. Of course, for high-level developers or some specific applications, developers can also directly use Cmake and Ninja commands to compile and download projects.
The command format of mdev build is:
➜ 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: is the path of the target application. The path must include the CMakeLists.txt file
MODULE: Hardware model. Select the BSP to use when running the application. The model supported by the command is the name of the mxos/module subdirectory
Options:
-c. -- clean: Before each compilation, clear the output file generated by the last compilation, and recompile
-f. -- flash [APP | ALL | None]: After compilation, the option to download to hardware
- APP: Only download applications
- ALL: Clear and download the complete Flash image
- None (default): Do not download
The compiled executable files, ELF files, memory usage and link data can be found in the build/<PROJECT>/directory.
Compilation example:
- Based on the EMC3080 module, compile the application program under the helloworld directory in the demos project.
➜ mxos-program cd demos ➜ demos git:(master) ✗ mdev build -c demos/helloworld emc3080
Based on the EMB1016 module, compile the application program under the at app/ble directory in the xbtdemo project, and download the application firmware to the module Flash after compilation.
➜ mxos-program cd xbtdemo ➜ xbtdemo git:(at-dev) mdev build -c at-app/ble emb1016 -f APP
#Compile static libraries
Each component will be compiled into a static library for connection. The static library can be found in the build folder or in the CMakelists of components Add a custom target in txt to automatically copy the generated static library. The following is an example of a component named xmesh that automatically copies the generated static library to the upper directory:
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
) Finally, generate such a static library as xmesh.Cortex-M33.GCC.release.a in the upper directory.
#Advanced Compilation
Mdev build actually uses Cmake and Ninja commands to build, so we can directly use cmake and ninja commands, which provides more flexibility and extensibility for advanced applications. The cmake and ninja commands corresponding to the mdev build - c at app/ble emb1016 - f APP command are as follows:
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
Among them, MXOS_ ENV is the root directory of various tools automatically downloaded by mdev. cmake searches the gcc compiler, CMAKE_ MAKE_ PROGRAM is the name of the make tool. Here is the ninja downloaded by mdev.
ninja -C build/at-app/ble-emb1016
#Push Changes
Submit the code changes through the git commit command, and use the git push command to push the remote code base.
It should be noted that if a component submits new changes to the code repository and needs to synchronize the changes to other developers, you need to use the mdev sync command to synchronize the connections in the component description file (. component file), and then update the code repository version of the project. Otherwise, other developers will still use the old component code base in projects imported by calling the mdev import or mdev deploy command.
_____________________________________________________________________________________________________________
END.