diff --git a/content/learning-paths/servers-and-cloud-computing/migrate-ease/1_codescanning.md b/content/learning-paths/servers-and-cloud-computing/migrate-ease/1_codescanning.md index c28cdfb76e..0eefe0da94 100644 --- a/content/learning-paths/servers-and-cloud-computing/migrate-ease/1_codescanning.md +++ b/content/learning-paths/servers-and-cloud-computing/migrate-ease/1_codescanning.md @@ -1,6 +1,6 @@ --- # User change -title: "Assess your code for migration to Arm" +title: "Assessing your code for migration to Arm" weight: 2 @@ -8,23 +8,23 @@ layout: "learningpathall" --- -### Common Arm Migration Challenges +### Common migration challenges -Migrating applications to Arm-based architectures is increasingly common across cloud, data center, and edge environments. Arm-powered servers and instances, available in AWS, Gooogle Cloud Platform, Microsoft Azure, Alibaba Cloud and Oracle Cloud Infrastructure (OCI), deliver significant performance-per-watt advantages and compelling cost-efficiency. +Migrating applications to Arm-based architectures is increasingly common across cloud, data center, and edge environments. Arm-powered servers and instances, available from AWS, Google Cloud Platform, Microsoft Azure, Alibaba Cloud, and Oracle Cloud Infrastructure (OCI), offer significant performance-per-watt advantages and compelling cost efficiency. -However, porting workloads to from one CPU architecture or another, can often require more than just recompilation. While many applications transition smoothly, others contain architecture-specific code or dependencies – developed originally for x86 – that can lead to build failures, runtime errors, or performance degradation on Arm systems. +However, porting workloads from one CPU architecture to another often requires more than simple recompilation. While many applications transition smoothly, others contain architecture-specific code or dependencies – originally developed for x86 – that can lead to build failures, runtime errors, or performance degradation on Arm systems. -Common challenges include detecting: -* Hardcoded x86 SIMD intrinsics -* Inline assembly -* Platform-specific system calls -* Unsupported compiler flags -* Non-portable build scripts or logic +Common challenges include issues with: +* Hardcoded x86 SIMD intrinsics. +* Inline assembly. +* Platform-specific system calls. +* Unsupported compiler flags. +* Non-portable build scripts or logic. In large or legacy codebases, these issues are often buried in third-party libraries or auto-generated components, making manual inspection slow and unreliable. -### Automated Analysis for Portability -To address these challenges, static code analysis tools play a critical role. Tools specifically designed for portability analysis enable developers to scan local codebases or remote repositories (e.g., GitHub) —and pinpoint architecture-specific constructs before attempting compilation or deployment on Arm. By surfacing portability concerns early in the development cycle, code scanning reduces time-to-first-build and helps prevent complex failures later. +### Automated analysis for portability +To address these challenges, static code analysis tools play a critical role. Tools specifically designed for portability analysis enable developers to scan local codebases or remote repositories (such as GitHub) and pinpoint architecture-specific constructs before attempting compilation or deployment on Arm. By surfacing portability issues early in the development cycle, code scanning reduces time-to-first-build and helps prevent complex failures later on. -In this learning path, you will learn about `migrate-ease`, a tool which allows developers to move beyond trial-and-error debugging to port their code to Arm. It provides clear, actionable insights into potential portability issues, detecting problematic patterns across many mainstream programming languages. These insights, combined with targeted refactoring, accelerate the process of making code portable, maintainable, and production-ready on Arm. +In this Learning Path, you'll use `migrate-ease`, a tool that helps developers move beyond trial-and-error debugging when porting their code to Arm. It provides clear, actionable insights into potential portability issues by detecting problematic patterns across widely used programming languages. These insights - combined with targeted refactoring - accelerate the process of making code portable, maintainable, and production-ready on Arm. diff --git a/content/learning-paths/servers-and-cloud-computing/migrate-ease/2_migrate_ease_spec.md b/content/learning-paths/servers-and-cloud-computing/migrate-ease/2_migrate_ease_spec.md index 215964eba5..23434d2efd 100644 --- a/content/learning-paths/servers-and-cloud-computing/migrate-ease/2_migrate_ease_spec.md +++ b/content/learning-paths/servers-and-cloud-computing/migrate-ease/2_migrate_ease_spec.md @@ -1,6 +1,6 @@ --- # User change -title: "Supported Programming Languages and Common Issues Identified" +title: "Migrate-ease and supported programming languages" weight: 3 @@ -10,51 +10,51 @@ layout: "learningpathall" ### What is migrate-ease? -[Migrate-ease](https://github.com/migrate-ease/) is a fork of [Porting advisor](https://github.com/arm-hpc/porting-advisor), an open-source project developed by Arm. Migrate-ease is maintained by the [OpenAnolis](https://github.com/openanolis) Arm Working Group. +[`Migrate-ease`](https://github.com/migrate-ease/) is a fork of [Porting Advisor](https://github.com/arm-hpc/porting-advisor), an open-source project developed by the Arm High Performance Computing Group. It is maintained by the [OpenAnolis](https://github.com/openanolis) Arm Working Group. -It is designed to analyze codebases specifically for `x86_64` architectures and offers tailored suggestions to facilitate the migration process to aarch64. -At present, this tool only supports codebase migration to Linux. The tool can be run on Arm or `x86_64` Linux machines. The tool does not modify any code, it inspects your code and provides recommendations. -It does not provide API level recommendations, and it does not send any data back to OpenAnolis. +`Migrate-ease` is designed to analyze codebases targeting `x86_64` architectures and offers tailored suggestions to facilitate migration to AArch64. The tool currently only supports migration to Linux-based environments and can be run on either `x86_64` or Arm AArch64 Linux machines. -### List of Supported Programming Languages +`Migrate-ease` is a read-only tool - it does not modify your code. It analyzes your source tree and provides architecture-specific recommendations. It does not provide API-level guidance, and it does not transmit data back to OpenAnolis. -This tool scans all files in a source tree, regardless of whether they are included by the build system or not. Currently, the tool supports the following languages/dependencies and the types of checks available for each launguage are shown: +### Supported programming languages and checks -#### C, C++ -- Inline assembly with no corresponding aarch64 inline assembly -- Assembly code with no corresponding aarch64 assembly code -- Use of architecture specific intrinsic -- Use of architecture specific compilation options -- Preprocessor errors that trigger when compiling on aarch64 -- Compiler specific code guarded by compiler specific pre-defined macros -- Missing aarch64 architecture detection in Makefile, Config.guess scripts -- Linking against libraries that are not available on the aarch64 architecture +The tool scans all files in a source tree, whether or not they are included by the build system. The following programming languages and dependency types are supported. For each language, the types of portability checks performed are listed. + +#### C and C++ +- Inline assembly with no corresponding AArch64 implementation. +- Architecture-specific assembly code. +- Use of architecture-specific intrinsics. +- Architecture-specific compilation options. +- Preprocessor errors triggered when compiling on AArch64. +- Compiler-specific code guarded by compiler-specific macros. +- Missing AArch64 detection logic in Makefile or `config.guess` scripts. +- Linking against libraries not available on AArch64. #### Go -- Inline assembly with no corresponding aarch64 inline assembly -- Assembly code with no corresponding aarch64 assembly code -- Use of architecture specific intrinsic -- Linking against libraries that are not available on the aarch64 architecture +- Inline assembly with no corresponding AArch64 implementation. +- Architecture-specific assembly code. +- Use of architecture-specific intrinsics. +- Linking against libraries unavailable on AArch64. #### Python -- Inline assembly with no corresponding aarch64 inline assembly -- Use of architecture specific intrinsic -- Linking against libraries that are not available on the aarch64 architecture -- Use of architecture specific packages +- Inline assembly with no corresponding AArch64 implementation. +- Use of architecture-specific intrinsics. +- Use of architecture-specific packages. +- Linking against libraries unavailable on AArch64. #### Rust -- Inline assembly with no corresponding aarch64 inline assembly -- Use of architecture specific intrinsic -- Linking against libraries that are not available on the aarch64 architecture +- Inline assembly with no corresponding AArch64 implementation. +- Use of architecture-specific intrinsics. +- Linking against libraries unavailable on AArch64. #### Java -- JAR scanning -- Dependency versions in `pom.xml` file -- A feature to detect native calls in Java source code -- Compatible version recommendations +- JAR dependency scanning. +- Version checks in `pom.xml` file. +- Detection of native method calls in Java source code. +- Recommendations for compatible versions. #### Dockerfile -- Use of architecture specific plugin -- The base image that dockerfile is based on does not support aarch64 +- Use of architecture-specific plugins. +- Base image does not support AArch64. diff --git a/content/learning-paths/servers-and-cloud-computing/migrate-ease/3_migrate_ease_run.md b/content/learning-paths/servers-and-cloud-computing/migrate-ease/3_migrate_ease_run.md index 5a902de00e..f8f52e7f9c 100644 --- a/content/learning-paths/servers-and-cloud-computing/migrate-ease/3_migrate_ease_run.md +++ b/content/learning-paths/servers-and-cloud-computing/migrate-ease/3_migrate_ease_run.md @@ -1,19 +1,14 @@ --- # User change -title: "Install migrate-ease" +title: "Getting started with migrate-ease" weight: 4 layout: "learningpathall" --- - -# migrate-ease - -[migrate-ease](https://github.com/migrate-ease/migrate-ease) is an open-source project designed to analyze codebases specifically for `x86_64` architectures and offers tailored suggestions aimed at facilitating the migration process to AArch64. This tool streamlines the transition, ensuring a smooth and efficient evolution of your software to leverage the benefits of aarch64 architecture. - -## Pre-requisites -Before you use `migrate-ease`, certain pre-requisites need to be installed: +## Set up your environment +Before using `migrate-ease`, install the following system dependencies: {{< tabpane code=true >}} {{< tab header="Ubuntu 22.04">}} sudo apt-get install -y python3 python3-pip python3-venv unzip libmagic1 git @@ -26,21 +21,19 @@ sudo dnf install -y python3 python3-pip unzip git {{< /tab >}} {{< /tabpane >}} -## Install and setup - -Start by checking out the repository with the tool's source code: +Clone the repository: ```bash git clone https://github.com/migrate-ease/migrate-ease cd migrate-ease ``` -At the root directory of migrate-ease, create and activate a python virtual environment: +Create and activate a Python virtual environment: ```bash python3 -m venv .venv source .venv/bin/activate ``` -Install the python packages dependencies and set the environment variable to point to it: +Install the required packages and set the environment variable: ```bash pip3 install -r requirements.txt export PYTHONPATH=`pwd` @@ -48,16 +41,16 @@ export PYTHONPATH=`pwd` ## Usage -You are now ready to use `migrate-ease` on your source code. You can use the tool either from the command-line or using a Web GUI. +You can use `migrate-ease` from the command-line or through a Web GUI. ### Command-line usage - -From the command-line, you can use the tool to scan your local codebases with different programming languages. The result from the code analysis is sent to console by default. + +You can scan local codebases written in a supported programming languages. By default, scan results from the code analysis are sent to the console. ```bash python3 -m {scanner_name} --arch {arch} {scan_path} ``` -The result from the scan can also be exported as `txt`, `csv`, `json` or `html`. You will need to specify this using the `--output` option: +The result from the scan can be exported as `txt`, `csv`, `json` or `html`. Specify this using the `--output` option: To generate a JSON report: ```bash @@ -68,15 +61,15 @@ Here's an explanation of each of the arguments passed to the scanner tool: **Parameters** -`{scanner_name}`: The name of the scanner, which can be one of cpp, docker, go, java, python or rust. +`{scanner_name}`: The name of the scanner, which can be one of cpp, docker, go, java, Python or rust. `{result_file_name}`: The name of the exported results file (without the extension). -`{arch}`: The architecture type, `aarch64` is the default. +`{arch}`: The architecture type; `aarch64` is the default. -`{scan_path}`: The path to the code that needs to be scanned. +`{scan_path}`: The path to the code you want to scan. -You can scan a remote git repository code base as well by passing the URL as shown in the example: +To scan a remote Git repository: ```bash python3 -m {scanner_name} --output {result_file_name}.json --arch {arch} --git-repo {repo} {clone_path} ``` @@ -86,23 +79,23 @@ There are more parameters for user to control the scan functionality. To see thi ```bash python3 -m {scanner_name} -h ``` -Replace {scanner_name} with either cpp, docker, go, java, python or rust. +Replace {scanner_name} with either cpp, docker, go, java, Python or rust. -### As Web UI -Migrate-ease also provides a Web UI that supports scanning a git repo with cpp, docker, go, java, python and rust scanners in one time. +### GUI +Migrate-ease also provides a Web UI that supports scanning a git repo with cpp, docker, go, java, Python and rust scanners in one time. To start the web server, simply run: ``` python3 web/server.py ``` -Once that is successfully done, you can access a web server hosted at http://localhost:8080 +Once the server is running, you can access a web server hosted at http://localhost:8080 -The web UI looks as following: -![example image alt-text#center](web_ui_index.jpg "Figure 1. Web UI to scan a git repo") +The web UI looks like this: +![example image alt-text#center](web_ui_index.jpg "Web UI to scan a git repo") -A git repo URL is required, and you can specify certain branch name to scan. Once the necessary information is filled, user can click "START SCAN" button to proceed project scanning. +A git repo URL is required, and you can specify certain branch name to scan. Once the necessary information is filled, you can click the **START SCAN** button to proceed project scanning. -Scanning progress will be shown in the console pane. Once all jobs are done, user will see a web page as following: -![example image alt-text#center](web_ui_result.jpg "Figure 2. Web UI of scan result") +Scanning progress is then shown in the console pane. Once all the jobs are done, you will see a web page like this: +![example image alt-text#center](web_ui_result.jpg "Web UI of scan result") -You can download the result by clicking the "download" icon or view the result by clicking the "eye" icon. +You can download the result by clicking the symbolic download icon button, or view the result by clicking the icon which looks like an eye. diff --git a/content/learning-paths/servers-and-cloud-computing/migrate-ease/4_migrate_ease_analysis.md b/content/learning-paths/servers-and-cloud-computing/migrate-ease/4_migrate_ease_analysis.md index 27bf269b50..9979d1578f 100644 --- a/content/learning-paths/servers-and-cloud-computing/migrate-ease/4_migrate_ease_analysis.md +++ b/content/learning-paths/servers-and-cloud-computing/migrate-ease/4_migrate_ease_analysis.md @@ -1,6 +1,6 @@ --- # User change -title: "An example of running migrate-ease" +title: "Try it out" weight: 5 @@ -8,16 +8,18 @@ layout: "learningpathall" --- ### Example use case -In this section, you will use the tool to scan the source code for [Protobuf](https://github.com/protocolbuffers/protobuf), a widely used library for serializing structured data. AArch64 support was Protobuf was introduced in version `v3.5.0` released in November 2017. For the purposes of demonstrating the usage of this tool, you will use an older version `v2.5.0` of Protobuf which lacks AArch64 support. +In this section, you'll use migrate-ease to scan the source code of [Protobuf](https://github.com/protocolbuffers/protobuf), a widely used library for serializing structured data. + +Support for AArch64 was added in Protobuf version `v3.5.0` (November 2017). To demonstrate how migrate-ease detects compatibility issues, you’ll scan an older version — `v2.5.0` — which lacks AArch64 support. Use `migrate-ease` to scan protobuf v2.5.0 and output the results to a JSON file named `result.json`: ```bash python3 -m cpp --git-repo https://github.com/protocolbuffers/protobuf.git --branch v2.5.0 --output result.json --arch aarch64 protobuf ``` -The output `result.json`, will be generated in your current directory once the scan is successfully executed. +The scan will generate a file called `result.json` in your current directory. -### How to interpret the results? -Open the `result.json` file. You will see it is organized in the following format: +### How to interpret the results +Open the `result.json` file. It contains structured output similar to this: ```output { "arch": "aarch64", @@ -113,23 +115,25 @@ Open the `result.json` file. You will see it is organized in the following forma "total_issue_count": 14 } ``` -You will need to check `issue_summary` and `issues` for the potential porting to AArch64 problems along with the suggested solutions. -The `issue_summary` provides an overview of the types of issues that the current scanner supports, along with the corresponding number of issues found. +* The `issue_summary` section provides a high-level overview of AArch64 compatibility issues found. +* The `issues` array lists each issue, including the file, line number, description, and a code snippet. + +### Issue type definitions -For each of the programming languages, the issue types are listed on the table: +Each supported language has its own set of issue types. The tables below describe these by category: {{< tabpane code=true >}} {{< tab header="C++, C">}} Name | Description ------------------------|------------------------------------------------------------------------------------------------------------- -ArchSpecificLibrary | Use of libraries strongly tied to the processor architecture, which may lead to compatibility issues. +ArchSpecificLibrary | Architecture-specific libraries that may cause issues on AArch64. AsmSource | Potentially architecture-specific assembly code in the source files that requires manual inspection. -Avx256Intrinsic | Use of AVX256 instructions on the AArch64 architecture lead to compatibility issues. -Avx512Intrinsic | Use of AVX512 instructions on the AArch64 architecture lead to compatibility issues. +Avx256Intrinsic | AVX256 instructions incompatible with AArch64. +Avx512Intrinsic | AVX512 instructions incompatible with AArch64. BuildCommand | Potential compatibility issues related to the compilation build commands. CPPLibRecommend | A better-optimized version of this library may be available. CPPLibVersion | This library version may be incompatible with the AArch64 architecture's compiler. -CPPStdCodes | Compatibility issues or optimization opportunities related to Cpp source and memory order on AArch64. +CPPStdCodes | Compatibility issues or optimization opportunities related to C++ source and memory order on AArch64. CompilerSpecific | Code is strongly tied to a compiler version or type, which may lead to compatibility issues. ConfigGuess | Config.guess file does not contain configurations for AArch64 and may require adaptation. CrossCompile | Cross-compilation compatibility issues. @@ -178,20 +182,22 @@ RustLinkLibrary | Use of libraries that are incompatible with the AArch64 arch {{< tab header="Dockerfile">}} Name | Description -------------------|----------------------------------------------------------------------------------------------------- -ConfigurationInfo | Configuration parameter used in ENV, ARG or LABEL refer an architecture that could not be supported. +ConfigurationInfo | Configuration parameter used in ENV, ARG or LABEL refers to an architecture that could not be supported. Image | A base image is used that might not support AArch64 architecture. Plugin | A package used in RUN, CMD or ENTRYPOINT does not support AArch64 architecture. {{< /tab >}} {{< /tabpane >}} -The `issues` is a list of those detected issues with details for each: +Each entry in the `issues` list contains: - `checkpoint`: A pattern to identify potential incompatibility. - `description`: The description of the detected issue. - `filename`: The file in which issue is detected. -- `issue_type`: The type of issue, including detailed descriptions of the error. -- `lineno`: The line number of the problematic code. -- `snippet`: The block of the problematic code. +- `issue_type`: Classification and explanation. +- `lineno`: Line number where the issue appears. +- `snippet`: A snippet of the relevant code. + +### Learn more -For more information about issue types refer to [migrate-ease github](https://github.com/migrate-ease/migrate-ease/blob/main/README.md). +For more information about issue types, see [migrate-ease github](https://github.com/migrate-ease/migrate-ease/blob/main/README.md). -You have successfully learnt how to install and use the `migrate-ease` scanner tools. You can now use it to scan your source code repositories to identify compatibility issues for aarch64 and use the provided recommendations for porting your code to Arm. +You have now learned how to install and use migrate-ease to scan a real-world project. You can now use it to scan your source code repositories to identify compatibility issues for AArch64 and use tool's insights to help port your code to Arm platforms. diff --git a/content/learning-paths/servers-and-cloud-computing/migrate-ease/_index.md b/content/learning-paths/servers-and-cloud-computing/migrate-ease/_index.md index 4efd360616..59b84e8bf7 100644 --- a/content/learning-paths/servers-and-cloud-computing/migrate-ease/_index.md +++ b/content/learning-paths/servers-and-cloud-computing/migrate-ease/_index.md @@ -1,22 +1,19 @@ --- -title: Migrate Applications to Arm Servers using migrate-ease +title: Migrate applications to Arm servers using migrate-ease -draft: true -cascade: - draft: true minutes_to_complete: 45 -who_is_this_for: This is an introductory topic for software developers looking to migrate their applications to Arm-based servers using a code analysis tool called migrate-ease. You can leverage this tool to scan source code repositories to identify porting issues you might encounter before migrating your code to run on Arm-based servers. +who_is_this_for: This is an introductory topic for developers looking to migrate applications to Arm-based servers using migrate-ease, a code analysis tool that scans source code repositories to identify architecture-specific porting issues before migration. learning_objectives: - - Examine your application's source code for architecture-specific dependencies - - Understand common migration challenges and their corresponding solutions - - Use migrate-ease to detect and address AArch64 code portability concerns + - Identify architecture-specific dependencies in your application's source code. + - Recognize common migration challenges and how to resolve them. + - Use migrate-ease to detect and address AArch64 portability issues. prerequisites: - - An [Arm based instance](/learning-paths/servers-and-cloud-computing/csp/) from a cloud service provider. + - Access to an [Arm-based instance](/learning-paths/servers-and-cloud-computing/csp/) for testing and validation. author: - Odin Shen @@ -30,8 +27,7 @@ armips: operatingsystems: - Linux tools_software_languages: - - Coding - - Neon + - NEON - SVE - Go - Runbook @@ -46,7 +42,7 @@ further_reading: link: https://www.arm.com/markets/computing-infrastructure/arm-cloud-migration type: website - resource: - title: Migrating applications to Arm servers + title: Migrating Applications to Arm Servers link: https://learn.arm.com/learning-paths/servers-and-cloud-computing/migration/ type: website