Packaging blueprint

How to package a blueprint

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 blueprint template from here.

Note that blueprint 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 : `blueprint-one`, `blueprint_two`
  Wrong name   : `blueprint_with-wrong_name`

Structure of blueprint templates

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

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

The standard structure of a blueprint template includes:

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

Two different data scenarios for blueprint are supported:

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

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

setup.py

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

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

setup(
    name="blueprint-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=['blueprint-one'],
    include_package_data=True,
    author="SoC.One Inc.",
    url="http://xplor.design",
    author_email="[email protected]",
    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 blueprint folder)
- packages - A list of strings specifying the packages that setuptools will manipulate. (That is the name of the installed blueprint 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 blueprint 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 (blueprint-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 = {'blueprint-two': 'blueprint-two/win32.x86_64'}
else:
    package_dir = {'blueprint-two': 'blueprint-two/linux.x86_64'}

Post-install and Pre-uninstall

Note:

If there are executable files that need to run after the blueprint 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 blueprint is uninstalled, please add pre-uninstall.sh/pre-uninstall.bat file (host specific) to the data folder.

xplor-studio-elf/
├── MANIFEST.in
├── setup.py
└── xplor-studio-elf
    ├── linux.x86_64
    │   ├── post-install.sh
    │   └── pre-uninstall.sh
    └── win32.x86_64
        ├── post-install.bat
        └── pre-uninstall.bat

Building blueprint

% 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 blueprint-one:
Rename folder blueprint-one → socone-blueprint
Replace string in setup.py, MANIFEST.in : blueprint-one → socone-blueprint

Example of creating Sample Blueprint

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

Download and extract the Sample Blueprint template from here.

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

Makefile

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

make clean
make

example image

MANIFEST.in

Just need to replace with Blueprint’s name

global-include xplor-studio-virt-qemu-baremetal-helloworld/**/*

setup.py

Update the Sample Blueprint’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.

xplor-studio-virt-qemu-baremetal-helloworld

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}/blueprints/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 blueprint 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.