Components

How to package a component

WARNING: The following guide is preliminary and subjected to changes.

Prerequisite

The following software components on the host computer are required:

python==3.8.10
setuptools (newest version)

Template

Download and extract the component template from here.

Note that component name should be in lowercases. If multiple words are used, they should be separated by underscores _ or -. Avoid using spaces or special characters or mixing _ and - in the package name.

Examples:

  Correct name : `component-one`, `component_two`
  Wrong name   : `component_with-wrong_name`

Structure of component templates

In the example component template, there are 2 folders (component-one/, component-two/) containing component templates and a Makefile that supports building and publishing components.

./
├── component-one
│   ├── component-one
│   │   └── Readme.md
│   ├── MANIFEST.in
│   └── setup.py
├── component-two
│   ├── component-two
│   │   ├── linux.x86_64
│   │   │   └── env
│   │   └── win32.x86_64
│   │       └── env
│   ├── MANIFEST.in
│   └── setup.py
└── Makefile

The standard structure of a component template includes:

A data folder (component-one/component-one, component-two/component-two)
MANIFEST.in (used for including non-Python data to package/component)
setup.py (used for building a component)

Two different data scenarios for component are supported:

The data of the component are host-independent, and can be used in both Windows and Linux OS (component-one)
The data of the component are host-dependent, requiring a different version for each supported host (component-two)

Limitation: components that have a mix of both common and specific data for different supported host are not yet supported.

setup.py

component-one/setup.py
```
from setuptools import setup

package_dir = {'component-one': 'component-one'}

setup(
    name="component-one",
    version="1.0.0",
    description="The baremetal example of the NEORV32 RISC-V Processor on Terrasic DE2-115 board",
    package_dir=package_dir,
    packages=['component-one'],
    include_package_data=True,
    author="SoC.One Inc.",
    url="http://xplor.design",
    author_email="info@soc.one",
    platforms=["Windows", "Linux"],
    long_description="The baremetal example of the NEORV32 RISC-V Processor on Terrasic DE2-115 board",
    license="Free",
    install_requires=[
        # Some dependencies here
    ],
    classifiers=[
        'Hardware'
    ]
)
```
Ref. https://setuptools.pypa.io/en/latest/references/keywords.html
- name - A string specifying the name of the package.
- version- A string specifying the version number of the package.
- description - A string describing the package in a single line.
- long_description - A string providing a longer description of the package.
- author - A string specifying the author of the package.
- author_email - A string specifying the email address of the package author.
- URL - A string specifying the URL for the package homepage.
- license - A string specifying the license of the package.
- platforms - A list of strings or comma-separated string. (Used to specify which OS is supported)
- package_dir - A dictionary that maps package names. (That maps the data folder with the installed component folder)
- packages - A list of strings specifying the packages that setuptools will manipulate. (That is the name of the installed component folder)
- install_requires - A string or list of strings specifying what other distributions need to be installed when this one is. (Dependencies concept)
- classifiers - A list of strings describing the categories for the package. (Classify a component as HW, SW, bitstream,… or something else)
- include_package_data - If True, setuptools will automatically include any data files it finds inside your package directories that are specified by your MANIFEST.in file. (Should be set to True to include non-Python data)

For (component-two), only some code need to be added to setup.py to specify package_dir for each supported host OS, as follow:

from setuptools import setup
import platform

if platform.system() == 'Windows':
    package_dir = {'component-two': 'component-two/win32.x86_64'}
else:
    package_dir = {'component-two': 'component-two/linux.x86_64'}

Post-install and Pre-uninstall

Note:

If there are executable files that need to run after the component is installed, please add post-install.sh/post-install.bat file (host specific) to the data folder.

If there are executable files that need to run before the component is uninstalled, please add pre-uninstall.sh/pre-uninstall.bat file (host specific) to the data folder.

rv-xplor-elf-linux64/
├── MANIFEST.in
├── pre-build.sh
├── rv-xplor-elf-linux64
│   ├── env.json
│   ├── post-install.sh
│   └── pre-uninstall.sh
└── setup.py

Building component

% python3 setup.py sdist

or % make build

Note:
If you’re reusing the example template, please rename the data folder and update the content of setup.py, MANIFEST.in
As an example, with component-one:
Rename folder component-one → socone-component
Replace string in setup.py, MANIFEST.in : component-one → socone-component

Example of Creating Example Project Component

This is an example of how to create a component for Baremetal Helloworld sample, running on QEMU simulator.

Download and extract the Sample component template from here.

Makefile
baremetal-virt-qemu-helloworld-example/
├── MANIFEST.in
├── setup.py
└── baremetal-virt-qemu-helloworld-example
    ├── src
    │   ├── main.c
    │   └── ...
    ├── settings
    ├── .cproject
    ├── .project
    └── project.json

Makefile

To clean or build the Sample component, use these commands:

make clean
make

example image

MANIFEST.in

Just need to replace with component’s name

global-include baremetal-virt-qemu-helloworld-example/**/*

setup.py

Update the Sample component’s information like name, description, platforms, dependencies …

example image

project.json

example image

Besides the basic information like Project’s Name, Project’s Type, Developer need to pay attention to Project’s language and Project’s category parameters.

XPLORSTUDIO IDE supports two kinds of Project’s language as C and CPP.
XPLORSTUDIO IDE supports the following list of Project’s categories:
Linux: RISC-V Embedded Linux Project
Baremetal: RISC-V Embedded Project
FreeRTOS: FreeRTOS Project
Zephyr: Zephyr Project
Linux_Kernel: Static Linux Kernel Project

Developer have to select the correct Project’s category from above list.

baremetal-virt-qemu-helloworld-example

Contains all resources of Eclipse’s project such as source code files, header files, linker script, libraries …

example image

In .cproject, it includes information of Project’s settings like managed build options, include paths, library paths …. Please, check the path of these resources, Developer should use the relative path, not the absolute path.

For example, to define the linker path:

  <option IS_BUILTIN_EMPTY="false" IS_VALUE_EMPTY="false" id="vio.managedbuild.elf.riscv.option.c.linker.paths.222877999" superClass="vio.managedbuild.elf.riscv.option.c.linker.paths" valueType="libPaths">
    <listOptionValue builtIn="false" value="&quot;${XPLOR_HOME}/xplor-platform/components/libraries/libpico/lib/virt/xplor&quot;"/>
    <listOptionValue builtIn="false" value=""/>
  </option>

Note: To support Windows environment, Developer should use " before and after the relative path of resource Naming convention of Example component is “xplor-studio----” Starting with prefix as “xplor-studio-” core: the name of running core such as Vexrisv, Neorv32, Corevmcu … platform: the name of running platform such as Qemu, DE2-115, Stratix10gx … rtos: the name of cateogry such as baremetal, linux, freertos … app: the name of application such as helloworld, timer, heap …

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.