ocpidev-project

Name

ocpidev-project — manage an OpenCPI project.

Synopsis

ocpidev [<options>] <verb> project <name>

DESCRIPTION

The project noun represents an OpenCPI project that holds and organizes OpenCPI assets. A project is a workspace in a directory where assets are developed. A project can contain:

Component libraries with component specifications, component unit test suites and workers (described in the OpenCPI Component Development Guide)
Applications (described in the OpenCPI Application Development Guide)
HDL primitives and HDL assemblies (described in the OpenCPI HDL Development Guide)
HDL devices, cards and slots (described in the OpenCPI HDL Development Guide)
Platform support assets (described in the OpenCPI Platform Development Guide)

A project has:

A defined directory structure for storing assets in both source and built forms
A project XML file (named Project.xml) that defines attributes for the project and some others to be applied to all assets in the project
A project asset document (named Project.rst) that serves as the "welcome" page for the project and as a directory to the assets documented in the project
An optional export file (named Project.exports) that specifies the assets and files that are to be visible to other projects that use this project’s assets

The ocpidev create operation produces a skeleton directory structure and initial versions of these files that can then be edited as necessary during project and asset development.

Unless suppressed by options, the ocpidev build operation compiles all assets and asset documents in the project and the ocpidev clean operation removes the compiled assets and asset documents from the project.

For details on project directory structure and how it is populated and built, see the chapter "Developing OpenCPI Assets in Projects" in the OpenCPI Component Development Guide. For details on OpenCPI asset documents and how to document a project, see the chapter "Documenting OpenCPI Assets" in the OpenCPI Documentation Writer Guide.

Verbs that can operate on a project are:

build: Build all assets and asset documents in the project. Use the --doc-only and --no-doc options to control the asset document building function.
clean: Remove all the generated and compiled files for all assets and asset documents in the project. Use the --doc-only and --no-doc options to control the asset document cleaning function.
create: Create the named project, creating files and directories as required. The project is created in a directory <name>, which must be a name without slashes. The project directory is created under the current working directory where ocpidev is executed. The general-purpose option -d <directory> can be used to create the project’s directory under a different directory.
delete: Remove all directories and files associated with the named project.
refresh: Manually regenerate the metadata associated with the project.
run: Run all applications and component unit test suites in the project.
show: Display information associated with the project.
[un]register: Register/unregister the named project in a registry.
utilization: Display usage information for all built workers, platforms, and assemblies contained in the project.

Note that an asset’s name is implied by the directory you’re in when you issue the ocpidev command. For projects, this means that you can perform operations (verbs) on the project without having to specify its name when you issue the ocpidev command from inside the project directory.

The ocpidev tool can also operate on a plural projects noun. The syntax is:

ocpidev [<options>] show projects

where show is the only valid verb, the default global scope is the only valid scope, and the valid options are -d <directory> and the show verb formatting options (--json, --simple, --table). The ocpidev show projects command displays information about all registered OpenCPI projects.

OPTIONS

In addition to the options common to all OpenCPI tools (see opencpi(1)), the options described below can be specified for operations on projects. In the following descriptions, a plus sign (+) after the option indicates that it can be specified more than once on the command line.

Options When Creating Projects

-A <directory>, --xml-include=<directory>+: Specify a directory to search for XML include files.
-D <package-ID>, --depend <package-ID>+: Specify the package-ID of a project on which the project being created depends.
-F <package-prefix>, --package-prefix=<package-ID>: Specify the package prefix of the created project. The default is local for projects.
-G <platform>, --only-platform=<platform>+: Only build the project for the specified platform.
-I <directory>, --include-dir=<directory>+: Specify a directory to search for include files (C, C++, Verilog).
-K <package-ID>, --package-id=<package-ID>: Specify the package-ID directly. The default is <package-prefix>.<package-name>.
-N <package-name>, --package-name=<package-name>: Specify the package name of the created project. The default is the <name> argument given after the create verb.
-Q <platform>, --exclude-platform=<platform>+: Do not build the project for the specified platform.
-T <target>, --only-target=<target>+: Only build the project for the specified HDL architecture.
-Y <primitive-library>, --prim-lib=<primitive-library>+: Specify a primitive library on which the project (or assets it contains) depends.
-Z <target>, --exclude-target=<target>+: Do not build the project for the specified HDL architecture.
-k, --keep: Keep files and directories created after a project creation fails. Normally, all such files and directories are removed on any failure.
-y <component-library>, --comp-lib=<component-library>+: Specify a component library to search for workers, devices and/or specs that this project (or assets it contains) references.
--register: Register the project as part of creating it.

Options When Deleting Projects

-f: Force deletion: do not ask for confirmation when deleting a project. Normally, you are asked to confirm a deletion.

Options When Building and Cleaning Projects

--doc-only: Only operate on the asset documents in the project and not on the other asset files in the project.
--no-doc: Only operate on the asset files in the project and not on the asset documents in the project.

Options When Building Projects

--hdl: Limit the assets being built to HDL primitives, workers, platforms or assemblies.
--hdl-assembly=<hdl-assembly>+: Limit the HDL assemblies being built to the specified assembly. This option can also be used in the hdl/assemblies directory.
--hdl-platform=<hdl-platform>+: Build HDL assets for the specified HDL platform.
--hdl-rcc-platform=<platform>+: Build RCC/ACI assets for the RCC platforms associated with the specified HDL platform. If this option is not used (and --rcc-platform <platform> is also not used), the current development software platform is used as the single RCC platform used for building.
--hdl-target=<target>+: Build HDL assets for the specified HDL architecture. If only HDL targets are specified (and no HDL platforms), containers are not built for HDL assemblies or component unit test suites.
--no-assemblies: Don’t build the HDL assemblies in the project. Building HDL assemblies (and their containers) can be slow.
--rcc: Limit the assets being built to RCC workers.
--rcc-platform=<platform>+: Build RCC/ACI assets for the specified RCC platform. If this option is not used (and --hdl-rcc-platform <platform> is also not used), the current development software platform is used as the single RCC platform used for building.
--optimimize: Build RCC/ACI assets with compiler optimization enabled. This results in a separate set of build outputs that do not conflict with non-optimized (debug) build outputs, since they are placed in a target directory whose name has a "-o" suffix.
--worker=<worker>+: Limits the assets being built to the specified worker.

Options When Running Projects

The options described here, when used in an "ocpidev run project" command, are applied as appropriate to all of the runnable assets (applications and unit test suites) that reside in the project. Note that any application-specific options supplied on the command line are only applied to XML applications and not to ACI applications.

Options That Apply to Applications and Unit Tests

--rcc-platform=<platform>+: Specify the RCC platform to use to build and generate the component unit test suites and build the ACI applications.

Options That Apply to Applications Only

--after=<args>+: Specify the argument(s) to insert at the end of the execution command line.
--before=<args>+: Specify the argument(s) to insert before the ACI executable or the ocpirun command; for example, environment settings or prefix commands.
--run-arg=<args>+: Specify the argument(s) to insert immediately after the ACI executable or the ocpirun command.

For details on how to use these options, see the section "Applications in Projects" in the OpenCPI Application Development Guide.

Options That Apply to Component Unit Test Suites Only

-G <platform>, --only-platform=<platform>+: Specify the runtime platform to use with a unit test suite.
-Q <platform>, --exclude-platform=<platform>: Specify the runtime platform to omit from a unit test suite.
-l <library>, --library=<library>: Run the unit test suite(s) in the specified library.
--accumulate-errors: Report execution or verification errors as they occur rather than ending the test on the first failure detected.
--hdl-platform=<platform>+: Specify the HDL platform to use with the component unit test suite. This option is only valid in generate and build phases.
--keep-simulations: Keep HDL simulation files regardless of verification results. By default, simulation files are removed if the verification is successful. Warning: Simulation files can become large!
--phase=<phase>+: Specify which non-building phase(s) of unit testing to run. Valid phases are: prepare, execute, verify, and view. The view phase is used to run only the view scripts for the unit test, without other phases. The --view option can be used to add viewing along with other phases.
--remotes=<system>: Specify the remote system to run the unit test suite(s) by setting the OCPI_REMOTE_TEST_SYS variable. See the section "Defining Remote Systems for Executing Tests" in the OpenCPI Component Development Guide for more information.
--view: Run the view script (view.sh) for the test at the conclusion of the test’s execution.

Options When Showing Projects

--global-scope: Show assets from all registered projects and the current project if applicable. This is the default scope used if -local-scope is not used.
--json: Format the output in JavaScript Object Notation (JSON) format, for integration with other software.
--local-scope: Only show assets in the local project.
--simple: Format the output as simply as possible.
--table: Display the output in an easy-to-read table. This is the default display format used if --simple or --json are not used.

Options When Using Utilization on Projects

--format{=table|latex}: Specify the format in which to output the usage information. Specifying table sends the information to stdout in tabular format. Specifying latex bypasses stdout and writes all output to utilization.inc files in the directories for the assets on which it operates.
--hdl-platform=<platform>+: Specify the buildable HDL platform for which to display usage information. This option can be specified more than once on the command line.

EXAMPLES

Create a project with the name my-project. This project’s package-ID will be local.my-project:
```
ocpidev create project my-project
```
Create a project with the package-prefix org.my-organization and the name my-project. This project’s package-ID will be org.my-organization.my-project:
```
ocpidev create project my-project -F org.my-organization
```
Build only the assets, not the documentation, in the assets project for the zed HDL platform and xilinx19_2_aarch32 RCC platform. Omit the name assets if inside the assets project.
```
ocpidev build project assets --hdl-platform zed
                             --rcc-platform xilinx19_2_aarch32
                             --no-doc
```
Clean the compiled asset documentation but not the compiled assets from the core project:
```
ocpidev clean project core --doc-only
```
Register the current project to its registry (or the default if it doesn’t have one yet):
```
ocpidev register project
```
Unregister the current project:
```
ocpidev unregister project
```
Run all the applications and unit tests in the project named MyProject:
```
ocpidev run project MyProject
```
Display information about the current project:
```
ocpidev show project
```
Show usage information for all supported assets in a project:
```
ocpidev utilization project
```
Record usage information in LaTeX format for all supported assets in a project:
```
ocpidev utilization project --format=latex
```

BUGS

See https://www.opencpi.org/report-defects

RESOURCES

See the main web site: https://www.opencpi.org

See the OpenCPI Component Development Guide: https://opencpi.gitlab.io/releases/latest/docs/OpenCPI_Component_Development_Guide.pdf

See the OpenCPI Documentation Writer Guide: https://opencpi.gitlab.io/releases/latest/docs/OpenCPI_Documentation_Writer_Guide.pdf

COPYING

Copyright (C) 2023 OpenCPI www.opencpi.org. OpenCPI is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.