### Setup Python Environment and Tree-sitter

Source: https://github.com/capstone-engine/capstone/blob/next/suite/auto-sync/README.md

Installs the Python virtual environment and activates it. Ensure Python version is at least 3.11. This is a prerequisite for installing the Auto-Sync framework.

```bash
cd <root-dir-Capstone>
# Python version must be at least 3.11
sudo apt install python3-venv
# Setup virtual environment in Capstone root dir
python3 -m venv ./.venv
source ./.venv/bin/activate
```

--------------------------------

### Install Auto-Sync Framework

Source: https://github.com/capstone-engine/capstone/blob/next/suite/auto-sync/README.md

Installs the Auto-Sync framework using pip. This command should be run after setting up the Python environment.

```bash
cd suite/auto-sync/ 
pip install -e .
```

--------------------------------

### Install Dependencies

Source: https://github.com/capstone-engine/capstone/blob/next/suite/auto-sync/RefactorGuide.md

Install the necessary Python package for the auto-sync suite.

```bash
pip install -e .
```

--------------------------------

### Install Java Native Access (JNA)

Source: https://github.com/capstone-engine/capstone/blob/next/bindings/java/README.md

Install the JNA library on Ubuntu using apt-get.

```bash
$ sudo apt-get install libjna-java
```

--------------------------------

### Example Input File Line

Source: https://github.com/capstone-engine/capstone/blob/next/suite/MC/README.md

An example demonstrating the format for a specific ARM architecture, mode, and options, followed by a sample assembly instruction.

```text
# CS_ARCH_ARM, CS_MODE_ARM+CS_MODE_V8, None
0xa0,0x0b,0x71,0xee = vadd.f64 d16, d17, d16
```

--------------------------------

### Install OpenJDK 6

Source: https://github.com/capstone-engine/capstone/blob/next/bindings/java/README.md

Install OpenJDK 6 JRE and JDK on Ubuntu using apt-get.

```bash
$ sudo apt-get install openjdk-6-jre-headless openjdk-6-jdk
```

--------------------------------

### Install Capstone Headers and Libraries

Source: https://github.com/capstone-engine/capstone/blob/next/CMakeLists.txt

Installs Capstone header files and libraries. Supports absolute installation paths and configures pkgconfig and CMake package files.

```cmake
if(CAPSTONE_INSTALL)
    include(GNUInstallDirs)
    install(FILES ${HEADERS_COMMON} DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/capstone)
    install(FILES ${HEADERS_INC} DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/capstone/inc)

    # Support absolute installation paths (discussion: https://github.com/NixOS/nixpkgs/issues/144170)
    if(IS_ABSOLUTE ${CMAKE_INSTALL_LIBDIR})
        set(CAPSTONE_PKGCONFIG_INSTALL_LIBDIR ${CMAKE_INSTALL_LIBDIR})
        set(CAPSTONE_CMAKE_INSTALL_LIBDIR ${CMAKE_INSTALL_LIBDIR})
    else()
        set(CAPSTONE_PKGCONFIG_INSTALL_LIBDIR "\${prefix}/${CMAKE_INSTALL_LIBDIR}")
        set(CAPSTONE_CMAKE_INSTALL_LIBDIR "\${PACKAGE_PREFIX_DIR}/${CMAKE_INSTALL_LIBDIR}")
    endif()
    if(IS_ABSOLUTE ${CMAKE_INSTALL_INCLUDEDIR})
        set(CAPSTONE_PKGCONFIG_INSTALL_INCLUDEDIR ${CMAKE_INSTALL_INCLUDEDIR})
        set(CAPSTONE_CMAKE_INSTALL_INCLUDEDIR ${CMAKE_INSTALL_INCLUDEDIR})
    else()
        set(CAPSTONE_PKGCONFIG_INSTALL_INCLUDEDIR "\${prefix}/${CMAKE_INSTALL_INCLUDEDIR}")
        set(CAPSTONE_CMAKE_INSTALL_INCLUDEDIR "\${PACKAGE_PREFIX_DIR}/${CMAKE_INSTALL_INCLUDEDIR}")
    endif()

    configure_file(capstone.pc.in ${CMAKE_BINARY_DIR}/capstone.pc @ONLY)
    install(FILES ${CMAKE_BINARY_DIR}/capstone.pc DESTINATION ${CMAKE_INSTALL_LIBDIR}/pkgconfig)

    include(CMakePackageConfigHelpers)
    set(CAPSTONE_CMAKE_CONFIG_INSTALL_DIR "${CMAKE_INSTALL_LIBDIR}/cmake/capstone")
    configure_package_config_file(
        capstone-config.cmake.in
        ${CMAKE_CURRENT_BINARY_DIR}/capstone-config.cmake
        INSTALL_DESTINATION ${CAPSTONE_CMAKE_CONFIG_INSTALL_DIR}
    )
    write_basic_package_version_file(
        ${CMAKE_CURRENT_BINARY_DIR}/capstone-config-version.cmake
        VERSION ${PROJECT_VERSION}
        COMPATIBILITY SameMajorVersion
    )

    install(FILES
        "${CMAKE_CURRENT_BINARY_DIR}/capstone-config.cmake"
        "${CMAKE_CURRENT_BINARY_DIR}/capstone-config-version.cmake"
        DESTINATION ${CAPSTONE_CMAKE_CONFIG_INSTALL_DIR}
    )

    if(CAPSTONE_BUILD_SHARED_LIBS)
        set(LIB_INSTALL_TARGETS capstone_shared)
    endif()

    if (CAPSTONE_BUILD_STATIC_LIBS)
        set(LIB_INSTALL_TARGETS ${LIB_INSTALL_TARGETS} capstone_static)
    endif()

    install(TARGETS ${LIB_INSTALL_TARGETS}
        EXPORT capstone-targets
        RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
        LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
        ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
        INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
    )

    install(EXPORT capstone-targets
            NAMESPACE capstone::
            DESTINATION ${CAPSTONE_CMAKE_CONFIG_INSTALL_DIR}
    )

    if (MSVC AND CAPSTONE_BUILD_SHARED_LIBS)
        install(
            FILES
            $<TARGET_PDB_FILE:capstone_shared>
            DESTINATION ${CMAKE_INSTALL_BINDIR}
            OPTIONAL
        )
    endif()

    # uninstall target
    if(NOT TARGET UNINSTALL)
        configure_file(
            "${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in"
            "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"
            IMMEDIATE @ONLY
        )
        add_custom_target(UNINSTALL COMMAND ${CMAKE_COMMAND} -P ${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake)
        set_target_properties(UNINSTALL PROPERTIES
            FOLDER CMakePredefinedTargets
        )
    endif()
endif()
```

--------------------------------

### Build and Install Capstone from Source

Source: https://github.com/capstone-engine/capstone/blob/next/bindings/python/README.md

Run this command within the Capstone source directory (containing setup.py) to build and install the Python bindings. Ensure you have a C compiler environment set up.

```bash
python -m pip install .
```

--------------------------------

### Install Capstone Python Bindings

Source: https://github.com/capstone-engine/capstone/blob/next/bindings/python/BUILDING.md

Use this command to install the Capstone Python bindings from a local source directory on *nix systems.

```bash
pip install bindings/python/
```

--------------------------------

### Install Python 3 Binding for Capstone

Source: https://github.com/capstone-engine/capstone/wiki/ChangeLog-from-2.1.2-to-3.0-rc1

Install the Python 3 module for Capstone by navigating to the bindings directory and running 'make install3'. Python 2 module installation remains the same.

```bash
cd bindings/python
sudo make install3
```

```bash
cd bindings/python
sudo make install
```

--------------------------------

### Install Cython Binding for Python

Source: https://github.com/capstone-engine/capstone/wiki/ChangeLog-2.0

Install Cython for improved Python binding performance. Ensure Cython is installed via pip or easy_install before proceeding.

```bash
$ sudo pip install cython    # or  sudo easy_install cython
$ cd bindings/python
$ sudo make install_cython
```

--------------------------------

### Execute Built Binary with QEMU

Source: https://github.com/capstone-engine/capstone/blob/next/BUILDING.md

Example command to run the 'cstool' binary with QEMU for cross-architecture testing, specifying the QEMU loader prefix.

```bash
QEMU_LD_PREFIX=/usr/s390x-redhat-linux/sys-root/fc40/usr/ qemu-s390x-static ./build/cstool -d aarch64 01421bd501423bd5
```

--------------------------------

### Install OCaml Toolchain on Ubuntu

Source: https://github.com/capstone-engine/capstone/blob/next/bindings/ocaml/README.md

Use this command to install the OCaml toolchain on Ubuntu systems. Ensure you have 'ocaml-nox' for the necessary components.

```bash
$	sudo apt-get install ocaml-nox
```

--------------------------------

### Install Capstone Core

Source: https://github.com/capstone-engine/capstone/wiki/Installing-on-Cygwin-&-Python3

Installs the compiled Capstone core library to the system. This makes the core functionality available for use.

```bash
./make.sh install
```

--------------------------------

### Install Capstone using pip

Source: https://github.com/capstone-engine/capstone/blob/next/bindings/python/README.md

Use this command to install the Capstone Python bindings from PyPI. This will automatically download a precompiled binary distribution suitable for your system.

```bash
pip install capstone
```

--------------------------------

### cstool Decoding Examples

Source: https://github.com/capstone-engine/capstone/blob/next/docs/cs_v6_release_guide.md

Demonstrates decoding instructions with different syntax options for PowerPC and x86 architectures.

```shell
$ cstool -s ppc32+percentage 0c100097
 0  0c 10 00 97  stwu   %r24, 0x100c(0)
$ cstool -s ppc32 0c100097
 0  0c 10 00 97  stwu   r24, 0x100c(0)
```

```shell
$ cstool -s x32+att 0c1097
 0  0c 10        orb    $0x10, %al
 2  97           xchgl  %eax, %edi
$ cstool -s x32+intel 0c1097
 0  0c 10        or     al, 0x10
 2  97           xchg   edi, eax
$ cstool -s x32+masm 0c1097
 0  0c 10        or     al, 10h
 2  97           xchg   edi, eax
```

```shell
$ cstool -s arm+regalias 0c100097000000008fa2000034213456
 0  0c 10 00 97  strls    r1, [r0, -ip]
 4  00 00 00 00  andeq    r0, r0, r0
 8  8f a2 00 00  andeq    sl, r0, pc, lsl #5
10  34 21 34 56  shasxpl  r2, r4, r4
$ cstool -s arm 0c100097000000008fa2000034213456
 0  0c 10 00 97  strls    r1, [r0, -r12]
 4  00 00 00 00  andeq    r0, r0, r0
 8  8f a2 00 00  andeq    r10, r0, pc, lsl #5
10  34 21 34 56  shasxpl  r2, r4, r4
```

--------------------------------

### Build with Specific Architecture Support

Source: https://github.com/capstone-engine/capstone/blob/next/BUILDING.md

Example of configuring Capstone to include support only for ARM and X86 architectures.

```bash
cmake -DCAPSTONE_ARM_SUPPORT=ON -DCAPSTONE_X86_SUPPORT=ON -S . -B build
```

--------------------------------

### Compile and Install Capstone Engine

Source: https://github.com/capstone-engine/capstone/wiki/ChangeLog-4.0-alpha1

Commands to compile and install the Capstone Engine from source. Ensure you run these commands in the root directory of the Capstone project.

```bash
    $ ./make.sh
    $ sudo ./make.sh install
```

--------------------------------

### Install Capstone Executable

Source: https://github.com/capstone-engine/capstone/blob/next/suite/cstest/CMakeLists.txt

Installs the 'cstest' executable to the specified destination directory if the 'CAPSTONE_INSTALL' option is enabled. This makes the executable available after installation.

```cmake
if(CAPSTONE_INSTALL)
    install(TARGETS cstest EXPORT capstone-targets DESTINATION ${CMAKE_INSTALL_BINDIR})
endif()
```

--------------------------------

### Install Capstone Python bindings and cstest_py

Source: https://github.com/capstone-engine/capstone/blob/next/tests/README.md

Install the necessary Python components for testing. This includes the Capstone Python bindings and the cstest_py tool. It's recommended to use a virtual environment.

```bash
# Optionally, create a new virtual environment
python3 -m venv .venv
source .venv/bin/activate

cd bindings/python
pip install -e .
pip install -e cstest_py
cd ../..
```

--------------------------------

### Select Runtime Architectures

Source: https://github.com/capstone-engine/capstone/blob/next/windowsce/COMPILE.md

Configure the Capstone binary to support specific architectures at runtime by setting DISASM_ARCH_LIST. This example enables ARM, ARM64, and x86 support.

```bat
set DISASM_ARCH_LIST=ARM ARM64 X86
```

--------------------------------

### Include Directories Setup

Source: https://github.com/capstone-engine/capstone/blob/next/suite/cstest/test/CMakeLists.txt

Configures include paths for the test build, including project-specific and general Capstone Engine directories.

```cmake
include_directories(${CSTEST_TEST_INC_DIR}
  ${CSTEST_INCLUDE_DIR}
  ${PROJECT_SOURCE_DIR}
  ${PROJECT_SOURCE_DIR}/include)
```

--------------------------------

### Cross Compilation with Toolchain File

Source: https://github.com/capstone-engine/capstone/blob/next/BUILDING.md

Example command for cross-compiling Capstone using a specified toolchain file and building static libraries.

```bash
cmake -DCMAKE_TOOLCHAIN_FILE=cross_configs/<cross_build_config>.cmake -DCAPSTONE_BUILD_STATIC_LIBS=ON -S . -B build
```

--------------------------------

### Compile and Install Capstone Engine

Source: https://github.com/capstone-engine/capstone/wiki/Next-branch

After updating the code, compile and install the Capstone engine using the provided shell scripts. This step is necessary to build the latest version.

```bash
$ ./make.sh
$ sudo ./make.sh install
```

--------------------------------

### Install Capstone Python3 Bindings

Source: https://github.com/capstone-engine/capstone/wiki/Installing-on-Cygwin-&-Python3

Compiles and installs the Python 3 bindings for Capstone from the 'bindings/python' directory. This allows Python scripts to interface with the Capstone library.

```bash
#----------------------------------------------------
#  You can use:  `pip3 install capstone`, BUT then 
#  you will miss out on new features! Use sources!
#----------------------------------------------------
cd bindings/python
make clean
make install3
```

--------------------------------

### Basic CMake Configuration

Source: https://github.com/capstone-engine/capstone/blob/next/tests/unit/CMakeLists.txt

Sets the minimum CMake version and enables testing. This is a standard starting point for CMake projects.

```cmake
cmake_minimum_required(VERSION 3.15)

enable_testing()
```

--------------------------------

### Install Cygwin Requirements

Source: https://github.com/capstone-engine/capstone/wiki/Installing-on-Cygwin-&-Python3

Installs essential packages on Cygwin using apt-cyg, including build tools and Python 3 development files. Ensure you have apt-cyg configured.

```bash
apt-cyg install base-cygwin base-files bind-utils diffutils
apt-cyg install coreutils binutils patch cygutils util-linux

apt-cyg install make cmake ncurses
apt-cyg install gcc-core gcc-g++ 
#apt-cyg install <countless other libraries>

apt-cyg install python3 python3-devel python3-pip
```

--------------------------------

### Custom Memory Allocation Build Configuration

Source: https://github.com/capstone-engine/capstone/blob/next/BUILDING.md

Example configuration for using custom memory allocations, enabling DIET and X86_REDUCE modes, and disabling system dynamic memory management.

```bash
cmake -DCAPSTONE_USE_SYS_DYN_MEM=0 -DCAPSTONE_BUILD_DIET=1 -DCAPSTONE_X86_REDUCE=1 -S . -B build
```

--------------------------------

### Windows Build Commands

Source: https://github.com/capstone-engine/capstone/blob/next/BUILDING.md

Commands for configuring, building, and installing Capstone on Windows. Specify the build configuration (e.g., 'Release' or 'Debug').

```bash
cmake.exe -B build
cmake.exe --build build --config Release # For debug build change "Release" to "Debug"
cmake.exe --install build
```

--------------------------------

### Get Auto-Sync Updater Help

Source: https://github.com/capstone-engine/capstone/blob/next/CONTRIBUTING.md

Run the `Auto-Sync` updater script with the -h flag to see a list of architectures it currently supports for updates.

```bash
suite/auto-sync/Updater/ASUpdater.py -h

```

--------------------------------

### Build cstest with CMake

Source: https://github.com/capstone-engine/capstone/blob/next/tests/README.md

Configure and build the cstest tool using CMake. Ensure libyaml is installed. Optionally enable AddressSanitizer with -DENABLE_ASAN=1.

```bash
# Install libyaml
# sudo apt install libyaml-dev
# or
# sudo dnf install libyaml-devel
cd "<capstone-repo-root>"
# Optionally add the -DENABLE_ASAN=1 flag.
cmake -B build -DCAPSTONE_BUILD_CSTEST=ON -DCMAKE_BUILD_TYPE=Debug
cmake --build build --config Debug
cmake --install build --prefix "<install-prefix>"
```

--------------------------------

### Unix Build Commands

Source: https://github.com/capstone-engine/capstone/blob/next/BUILDING.md

Standard commands for configuring, building, and installing Capstone on Unix-like systems. Use 'Debug' instead of 'Release' for a debug build.

```bash
cmake -B build -DCMAKE_BUILD_TYPE=Release # For debug build change "Release" to "Debug"
cmake --build build
cmake --install build --prefix "<install-prefix>"
```

--------------------------------

### Generate, Translate, and Patch Files

Source: https://github.com/capstone-engine/capstone/blob/next/suite/auto-sync/RefactorGuide.md

Run the ASUpdater to generate, translate, and patch architecture files, including copying translated files. Use without '-w' after initial setup to avoid overwriting manual fixes.

```bash
ASUpdater -a <ARCH> -w --copy-translated -s IncGen Translate PatchArchHeader
```

--------------------------------

### Checkout and Compile Next Branch

Source: https://github.com/capstone-engine/capstone/wiki/ChangeLog-2.1

Commands to pull the latest changes, checkout the 'next' branch, and compile and install the Capstone engine. This is essential for testing the newest features.

```bash
git pull
git checkout next
```

```bash
./make.sh
sudo ./make.sh install
```

```bash
git pull origin next
```

```bash
git checkout master
```

--------------------------------

### Install cstest_py for Disassembler Tests

Source: https://github.com/capstone-engine/capstone/blob/next/bindings/python/BUILDING.md

Install `cstest_py` to run disassembler tests. This package is an alternative to `cstest` and supports Windows and Mac.

```bash
pip install bindings/python/cstest_py/
```

--------------------------------

### Build Compact Binaries with Diet Mode

Source: https://github.com/capstone-engine/capstone/blob/next/BUILDING.md

Enable 'DIET' mode to make Capstone binaries more compact.

```bash
cmake -DCAPSTONE_BUILD_DIET=ON -S . -B build
```

--------------------------------

### Build All Architectures with CMake

Source: https://github.com/capstone-engine/capstone/blob/next/BUILDING.md

Command to build Capstone with all architectures enabled by default.

```bash
cmake -DCAPSTONE_ARCHITECTURE_DEFAULT=ON -S . -B build
```

--------------------------------

### Inhibit Native Core Build during Installation

Source: https://github.com/capstone-engine/capstone/blob/next/bindings/python/README.md

Set the LIBCAPSTONE_PATH environment variable to prevent the automatic build of the Capstone native core during Python package installation. This is useful if you have a pre-installed libcapstone.

```bash
export LIBCAPSTONE_PATH=1
```

--------------------------------

### Update MC regression tests

Source: https://github.com/capstone-engine/capstone/blob/next/tests/README.md

Update the YAML MC regression tests by running the MCUpdater script. This requires installing Auto-Sync and having llvm-mc and FileCheck installed. Replace 'ARCH' with the target architecture.

```bash
cd suite/auto-sync/
# Follow install instructions of Auto-Sync described in the README
# And run the updater:
./src/autosync/MCUpdater.py -a ARCH
ls build/mc_out/
```

--------------------------------

### Download Capstone Sources

Source: https://github.com/capstone-engine/capstone/wiki/Installing-on-Cygwin-&-Python3

Clones the Capstone repository from GitHub to your home directory. This is the first step in building from source.

```bash
cd $HOME
git clone https://github.com/aquynh/capstone.git
cd capstone
```

--------------------------------

### Basic CMake Configuration

Source: https://github.com/capstone-engine/capstone/blob/next/suite/cstest/test/CMakeLists.txt

Sets the minimum required CMake version and defines source and include directories for tests.

```cmake
cmake_minimum_required(VERSION 3.15)

set(CSTEST_TEST_SRC_DIR ${CSTEST_TEST_DIR}/src)
set(CSTEST_TEST_INC_DIR ${CSTEST_TEST_DIR}/include)
```

--------------------------------

### Check ASUpdater Help

Source: https://github.com/capstone-engine/capstone/blob/next/suite/auto-sync/README.md

Displays the help message for the ASUpdater script, showing available options and usage.

```bash
ASUpdater -h
```

--------------------------------

### Troubleshoot Unrecognized Sanitizer Argument

Source: https://github.com/capstone-engine/capstone/blob/next/suite/fuzz/README.md

If you encounter an error with '-fsanitize=', ensure you have a compatible libfuzz version installed. Try building with CC=clang.

```bash
CC=clang make
```

--------------------------------

### Build cstest with libyaml Dependency

Source: https://github.com/capstone-engine/capstone/blob/next/BUILDING.md

Enable the build of 'cstest' located in 'suite/cstest/'. Note that 'cstest' requires 'libyaml', which it attempts to build from source if not found.

```bash
cmake -DCAPSTONE_BUILD_CSTEST=ON -S . -B build
```

--------------------------------

### Original C code for accessing instruction details

Source: https://github.com/capstone-engine/capstone/wiki/ChangeLog-2.0

Example of how instruction detail fields were accessed before version 2.0. This syntax is now deprecated.

```c
        if (insn.regs_read_count > 0)
```

--------------------------------

### Enable Module Registration for Static Libraries

Source: https://github.com/capstone-engine/capstone/blob/next/BUILDING.md

Configure Capstone to use dynamic module registration, allowing consumers to register only the architectures they need.

```bash
cmake -DCAPSTONE_USE_ARCH_REGISTRATION=1 -S . -B build
```

--------------------------------

### Unix Package Generation

Source: https://github.com/capstone-engine/capstone/blob/next/BUILDING.md

Commands to generate Debian, RPM, and OSX packages. Ensure to set the build type and installation prefix appropriately.

```bash
cmake -B build -DCMAKE_BUILD_TYPE=Release -DCAPSTONE_BUILD_SHARED_LIBS=1 -DCMAKE_INSTALL_PREFIX=/usr
cmake --build build
cd build
cpack -G DEB
cpack -G RPM
cpack -G DragNDrop
```

--------------------------------

### Format Code with Black and Usort

Source: https://github.com/capstone-engine/capstone/blob/next/suite/auto-sync/README.md

Install and use black and usort to format CppTranslator files. Run these commands after making changes to the CppTranslator.

```bash
pip3 install black usort
```

```bash
python3 -m usort format src/autosync
```

```bash
python3 -m black src/autosync
```

--------------------------------

### Sample Code for cs_disasm_buf Usage

Source: https://github.com/capstone-engine/capstone/wiki/New-APIs:-cs_disasm_alloc()-&-cs_disasm_buf()

This C-pseudo code demonstrates how to use `cs_disasm_malloc` to pre-allocate a buffer and `cs_disasm_buf` to fill it with disassembled instructions, followed by freeing the memory.

```c
if (cs_disasm_malloc(h, count, &insns) == CS_ERR_OK) {
    // mycount <= count
    while(c = cs_disasm_buf(h, code, size, address, mycount, insns)) {
        // analyze *c* instructions in @insns ...

        // then update input code/size/address for the next iteration
        length = CS_INSN_OFFSET(insns, c);
        code += length;
        size -= length;
        address += length;
    }

    // free memory when done
    cs_free(insns, count);
}
```

--------------------------------

### Basic CMake Configuration

Source: https://github.com/capstone-engine/capstone/blob/next/BUILDING.md

Standard command to configure Capstone build with CMake, specifying the source and build directories.

```bash
cmake -S . -B build
```

--------------------------------

### Checkout LLVM

Source: https://github.com/capstone-engine/capstone/blob/next/contrib/riscv_update/README.md

Clone the LLVM repository and checkout a specific commit for testing.

```bash
git clone https://github.com/llvm/llvm-project.git
git checkout b81d715c
```

--------------------------------

### Test Python Scripts

Source: https://github.com/capstone-engine/capstone/wiki/Installing-on-Cygwin-&-Python3

Executes all provided Python test scripts to ensure the Capstone installation and bindings are functioning correctly. This is a comprehensive verification step.

```bash
python3 test_all.py
```

--------------------------------

### Fix C++ Namespace Prefix

Source: https://github.com/capstone-engine/capstone/blob/next/suite/auto-sync/RefactorGuide.md

Correct missing namespace prefixes in C++ code translations. For example, `unsigned GR32Regs[]` should become `unsigned ARCH_GR32Regs[]`.

```cpp
unsigned GR32Regs[]
```

```cpp
unsigned ARCH_GR32Regs[]
```

--------------------------------

### Get Help for Capstone Disassembly Command

Source: https://github.com/capstone-engine/capstone/blob/next/bindings/powershell/README.md

Obtain detailed usage information for the Capstone disassembly command by using the 'Get-Help' cmdlet with the '-Full' parameter.

```powershell
Get-Help Get-CapstoneDisassembly -Full
```

--------------------------------

### Executable and Dependency Configuration

Source: https://github.com/capstone-engine/capstone/blob/next/suite/cstest/test/CMakeLists.txt

Globally finds C source files for the unit test executable, adds it, and links it against the Capstone library.

```cmake
file(GLOB CSTEST_TEST_SRC ${CSTEST_TEST_SRC_DIR}/*.c)
add_executable(unit_test ${CSTEST_TEST_SRC})
add_dependencies(unit_test libcstest)
target_link_libraries(unit_test PUBLIC libcstest)
```

--------------------------------

### Check PIP Package Version

Source: https://github.com/capstone-engine/capstone/wiki/Installing-on-Cygwin-&-Python3

Displays the installed version of the capstone package in your Python environment using pip3. Useful for confirming the correct version is active.

```bash
pip3 list |grep capstone
```

--------------------------------

### Verify Python Bindings Version

Source: https://github.com/capstone-engine/capstone/wiki/Installing-on-Cygwin-&-Python3

Checks if the Python core and API bindings versions match using a Python 3 one-liner. This ensures compatibility after installation.

```python
python3 -c "from capstone import *; version_bind(); cs_version(); print(version_bind() == cs_version())"
```

--------------------------------

### Compile Capstone Core

Source: https://github.com/capstone-engine/capstone/wiki/Installing-on-Cygwin-&-Python3

Cleans previous build artifacts and compiles the core Capstone library using the GCC toolchain. This step is crucial before installing bindings.

```bash
make clean
./make.sh gcc
```

--------------------------------

### Configure Toolchain Binaries Path

Source: https://github.com/capstone-engine/capstone/blob/next/windowsce/COMPILE.md

Provide a semicolon-separated list of directories containing the Windows CE toolchain binaries.

```bat
set TOOLCHAIN=%WINCE_TOOLCHAIN_ROOT%\Bin\i386\Arm;%WINCE_TOOLCHAIN_ROOT%\Bin\i386
```

--------------------------------

### Reinstall Python Bindings for Capstone

Source: https://github.com/capstone-engine/capstone/wiki/ChangeLog-4.0-alpha1

Instructions to reinstall Python bindings after updating the Capstone core. Navigate to the Python bindings directory and run 'make install'.

```bash
$ cd bindings/python
$ sudo make install
```

--------------------------------

### Build Capstone for Android with NDK

Source: https://github.com/capstone-engine/capstone/blob/next/BUILDING.md

Configure Capstone build for Android using the NDK's toolchain file and specifying the target ABI.

```bash
cmake -B build -DCMAKE_TOOLCHAIN_FILE=$NDK_PATH/build/cmake/android.toolchain.cmake -DANDROID_NDK=$NDK_PATH -DANDROID_ABI=arm64-v8a
```

--------------------------------

### Decode Instructions with cs_disasm_iter()

Source: https://github.com/capstone-engine/capstone/blob/next/tests/integration/README.md

Demonstrates how to use the cs_disasm_iter() API to decode instructions one at a time within a loop. Ensure Capstone is initialized before use.

```c
#include <capstone.h>

// ... initialization code ...

cs_insn *insn;
while (cs_disasm_iter(handle, &code, &size, &offset, insn))
{
    // Process the instruction pointed by insn
    // ...
}

// ... cleanup code ...

```

--------------------------------

### Configure Linker Directives for Libraries

Source: https://github.com/capstone-engine/capstone/blob/next/windowsce/COMPILE.md

Provide a space-separated list of linker directives to control library searching. This example shows directives for Windows CE 7.

```bat
set LIBS=-nodefaultlib:oldnames.lib -nodefaultlib:libcmtd.lib -nodefaultlib:libcmt.lib coredll.lib corelibc.lib
```

```bat
set LIBS=coredll.lib
```

--------------------------------

### s390x cdpt Instruction Encoding

Source: https://github.com/capstone-engine/capstone/blob/next/suite/auto-sync/src/autosync/Tests/MCUpdaterTests/Disassembler/SystemZ/test_systemz_mapping.txt

Demonstrates the encoding of the 'cdpt' instruction with different operand variations for s390x architecture. Use these examples to verify instruction encoding.

```assembly
# For z13 and above.
# RUN: llvm-mc -triple s390x-linux-gnu -mcpu=z13 -show-encoding %s \
# RUN:   | FileCheck %s
# RUN: llvm-mc -triple s390x-linux-gnu -mcpu=arch11 -show-encoding %s \
# RUN:   | FileCheck %s

#CHECK: cdpt	%f0, 0(1), 0                # encoding: [0xed,0x00,0x00,0x00,0x00,0xae]
#CHECK: cdpt	%f15, 0(1), 0               # encoding: [0xed,0x00,0x00,0x00,0xf0,0xae]
#CHECK: cdpt	%f0, 0(1), 15               # encoding: [0xed,0x00,0x00,0x00,0x0f,0xae]
#CHECK: cdpt	%f0, 0(1, %r1), 0            # encoding: [0xed,0x00,0x10,0x00,0x00,0xae]
```

```assembly
	cdpt	%f0, 0(1), 0
	cdpt	%f15, 0(1), 0
	cdpt	%f0, 0(1), 15
	cdpt	%f0, 0(1, %r1), 0
```

--------------------------------

### Build Capstone Executable and Library

Source: https://github.com/capstone-engine/capstone/blob/next/suite/cstest/CMakeLists.txt

Configures the build process for the 'cstest' executable and 'libcstest' static library. It finds source files and adds dependencies.

```cmake
set(CSTEST_INCLUDE_DIR ${CSTEST_DIR}/include)
file(GLOB CSTEST_SRC ${CSTEST_DIR}/src/*.c)
add_executable(cstest ${CSTEST_SRC})
add_library(libcstest STATIC ${CSTEST_SRC})
set_property(TARGET libcstest PROPERTY OUTPUT_NAME cstest)
```

--------------------------------

### Generate Coverage Files

Source: https://github.com/capstone-engine/capstone/blob/next/BUILDING.md

Configure the build to generate code coverage files.

```bash
cmake -DENABLE_COVERAGE=ON -S . -B build
```

--------------------------------

### Build Legacy Integration Tests

Source: https://github.com/capstone-engine/capstone/blob/next/BUILDING.md

Enable the build of some legacy integration tests for Capstone.

```bash
cmake -DCAPSTONE_BUILD_LEGACY_TESTS=ON -S . -B build
```

--------------------------------

### Compile Capstone OCaml Bindings

Source: https://github.com/capstone-engine/capstone/blob/next/bindings/ocaml/README.md

Run 'make' in the command line within the Capstone OCaml binding directory to compile the bindings. This assumes the OCaml toolchain is already installed.

```bash
make
```

--------------------------------

### Build Shared Libraries

Source: https://github.com/capstone-engine/capstone/blob/next/BUILDING.md

Enable the build of shared libraries for Capstone.

```bash
cmake -DCAPSTONE_BUILD_SHARED_LIBS=ON -S . -B build
```

--------------------------------

### Configure libyaml Build

Source: https://github.com/capstone-engine/capstone/blob/next/suite/cstest/CMakeLists.txt

Attempts to find libyaml on the system. If not found, it configures the build to download and build libyaml using ExternalProject. This is crucial for systems lacking a package manager or for cross-compilation.

```cmake
# libyaml is used to parse the test files.
# Normally it can be installed via the package managers,
# but Windows and cross-compile targets might not have it.
# So it builds it optionally as well.
set(USE_BUILT_LIBYAML false)
find_library(libyaml NAMES libyaml yaml)
if (NOT libyaml)
    # Build libyaml
    set(USE_BUILT_LIBYAML true)
    message("System libyaml: NO - Building it.")
    set(LIBYAML_LIB_FILE "${CMAKE_CURRENT_BINARY_DIR}/extern/src/libyaml_ext-build/libyaml.a")
    set(LIBYAML_LIBRARY_DIRS "${CMAKE_CURRENT_BINARY_DIR}/extern/src/libyaml_ext-build/")
    set(LIBYAML_INCLUDE_DIRS "${CMAKE_CURRENT_BINARY_DIR}/extern/src/libyaml_ext/include")
    ExternalProject_Add(libyaml_ext
        PREFIX extern
        URL "https://github.com/yaml/libyaml/archive/refs/tags/0.2.5.tar.gz"
        URL_HASH SHA256=fa240dbf262be053f3898006d502d514936c818e422afdcf33921c63bed9bf2e
        # URL "https://github.com/yaml/libyaml/archive/refs/tags/0.1.7.tar.gz"
        # URL_HASH SHA256=e1884d0fa1eec8cf869ac6bebbf25391e81956aa2970267f974a9fa5e0b968e2
        CMAKE_ARGS
            -DCMAKE_POLICY_VERSION_MINIMUM=3.5
            -DBUILD_TESTING=OFF
            -DBUILD_SHARED_LIBS=OFF
            -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
            -DANDROID_NDK=${ANDROID_NDK}
            -DANDROID_PLATFORM=${ANDROID_PLATFORM}
            -DANDROID_ABI=${ANDROID_ABI}
            -DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}
        BUILD_BYPRODUCTS "${LIBYAML_LIB_FILE}"
        INSTALL_COMMAND ""
    )
    add_library(libyaml_built STATIC IMPORTED)
    set_target_properties(libyaml_built PROPERTIES IMPORTED_LOCATION "${LIBYAML_LIB_FILE}")
    set_target_properties(libyaml_built PROPERTIES INCLUDE_DIRECTORIES "${LIBYAML_INCLUDE_DIRS}")
    set_target_properties(libyaml_built PROPERTIES LIBRARY_DIRECTORIES "${LIBYAML_LIB_DIR}")
else()
    message("System libyaml: YES")
endif()
```