Name

ocpixml — command-line tool for managing artifact description XML in OpenCPI artifact files and standalone XML files

Synopsis

ocpixml [<options>] <verb> <file>[<file>]

DESCRIPTION

The ocpixml(1) command-line tool is used to manage the artifact description XML that exists inside an OpenCPI artifact file generated by the ocpidev(1) build operation. It can also be used to parse any standalone XML file.

The artifact description XML describes the contents of an executable binary (an artifact resulting from building an RCC or HDL worker or a component unit test) or a "bitstream" executable (an artifact resulting from building an HDL assembly) and is attached during the build process to the generated executable or bitstream (.bitz or .gz) artifact file. The ocpixml tool can be used to manipulate the artifact description XML attached to an artifact file.

For convenience, options can occur anywhere in the command. When invoked without options and verbs, ocpixml displays help information.

VERBS

The verbs supported by ocpixml are:

add
Add the named XML file or stdin (indicated with a hyphen) to the named artifact file, in place.
get
Extract the artifact description XML from the named artifact file to stdout.
parse
Parse the top-level XML attributes from the named XML file to stdout.
strip
Remove the artifact description XML from the named artifact file and copy it to another named artifact file.

NOUNS

None.

OPTIONS

In addition to the general-purpose options common to all OpenCPI tools (see opencpi(1)), the options described below can be specified for ocpixml operations. In the following descriptions, a plus sign (+) after the option indicates that it can be specified more than once on the command line. Arguments to word-form options are preceded by an equal sign (=) (as shown in the following descriptions) or a space. Arguments to letter options are preceded by a space.

Options That Apply to All Operations

-s, --silent
Only output exit status, not informational or error messages generated during execution.

Options That Apply to Parse Operations

-a <attribute-name>, --attribute=<attribute-name>+
Specify the attribute(s) to output from the XML file, one attribute per line. An attribute name that starts with a question mark (?) is optional and outputs as a blank line if it is not present; otherwise, it is an error if it is not present. If this option is not used, the top element name is output.
-t <top-element-name>, --top=<top-element-name>+
Specify the top-level element(s) in the XML file to parse and generate an error if the specified value(s) is/are not the top-level element tag(s).

EXAMPLES

  1. Add the content of the XML file named MyFile.xml to the artifact file named myartifact1.bitz and only output exit status: 

    ocpixml -s add myartifact1.bitz MyFile.xml

  2. Add standard input to the artifact file named myartifact1.gz: 

    ocpixml add myartifact1.gz -

  3. Extract the XML metadata from the artifact file named myartifact1.bitz and write it to stdout: 

    ocpixml get myartifact1.bitz

  4. Parse the top-level element1 and the attributes attr1 and attr2 from the XML file named MyFile.xml and write them to stdout. Generate an error if element1 and attr1 are not present. Generate a blank line if attr2 is not present. 

    ocpixml -t element1 -a attr1 -a ?attr2 parse MyFile.xml

  5. Remove the XML metadata from the artifact file named myartifact1.gz and copy the results to the artifact file named mynewartifact1.gz: 

    ocpixml strip myartifact1.gz mynewartifact1.gz

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 HDL Development Guide: https://opencpi.gitlab.io/releases/latest/docs/OpenCPI_HDL_Development_Guide.pdf

SEE ALSO

ocpidev-assembly(1) ocpidev-build(1) ocpidev-platform(1) ocpidev-test(1) ocpidev-worker(1)

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.