Difference between revisions of "XCDL packages"
m (→Package Versioning) |
m (→Package contents and layout) |
||
| Line 92: | Line 92: | ||
== Package contents and layout == | == Package contents and layout == | ||
| − | + | A typical package contains the following: | |
| + | |||
| + | # Some number of source files which will end up in a library. The application code will be linked with this library to produce an executable. Some source files may serve other purposes, for example to provide a linker script. | ||
| + | # Exported header files which define the interface provided by the package. | ||
| + | # On-line documentation, for example reference pages for each exported function. | ||
| + | # Some number of test cases, shipped in source format, allowing users to check that the package is working as expected on their particular hardware and in their specific configuration. | ||
| + | # One or more CDL scripts describing the package to the configuration system. | ||
| + | |||
| + | It is also conventional to have a per-package ''ChangeLog'' file used to keep track of changes to that package. This is especially valuable to end users of the package who may not have convenient access to the source code control system used to manage the master copy of the package, and hence cannot find out easily what has changed. Often it can be very useful to the main developers as well. | ||
| + | |||
| + | Any given packages need not contain all of these. It is compulsory to have at least one XCDL file describing the package, otherwise the component framework would be unable to process it. Some packages may not have any source code: it is possible to have a package that merely defines a common interface which can then be implemented by several other packages, especially in the context of device drivers; however it is still common to have some code in such packages to avoid replicating shareable code in all of the implementation packages. Similarly it is possible to have a package with no exported header files, just source code that implements an existing interface: for example an ethernet device driver might just implement a standard interface and not provide any additional functionality. Packages do not need to come with any on-line documentation, although this may affect how many people will want to use the package. Much the same applies to per-package test cases. | ||
| + | |||
| + | The component framework has a recommended per-package folder layout which splits the package contents on a functional basis: | ||
| + | |||
| + | <pre> | ||
| + | Packages/ARM/CMSIS/current | ||
| + | ├── ChangeLog | ||
| + | ├── doc | ||
| + | ├── include | ||
| + | ├── meta | ||
| + | │ └── xcdl.xml | ||
| + | ├── src | ||
| + | └── tests | ||
| + | </pre> | ||
| + | |||
| + | For example, if a package has an ''include'' sub-folder then the component framework will assume that all header files in and below that folder are exported header files and will do the right thing at build time. Similarly if there is ''doc'' property indicating the location of on-line documentation then the component framework will first look in the doc sub-folder. | ||
| + | This folder layout is just a guideline, it is not enforced by the component framework. For simple packages it often makes more sense to have all of the files in just one directory. For example a package could just contain the files hello.cpp, hello.h, hello.html and xcdl.xml. By default hello.h will be treated as an exported header file, although this can be overridden with the includeFiles property. Assuming there is a doc property referring to hello.html and there is no doc sub-directory then the tools will search for this file relative to the package’s top-level and everything will just work. Much the same applies to hello.cpp and xcdl.xml. | ||
=== Outline of the build process === | === Outline of the build process === | ||
Revision as of 18:27, 21 June 2014
For a package to be usable in the XCDL component framework it must conform to certain rules imposed by that framework. Packages must be distributed in a form that is understood by the component repository administration tool. There must be a top-level XCDL file which describes the package to the component framework. There are certain limitations related to how a package gets built, so that the package can still be used in a variety of host environments. In addition to these rules, the component framework provides a number of guidelines. Packages do not have to conform to the guidelines, but sticking to them can simplify certain operations.
Contents
Repositories
Packages and the local component repository
All development tools using XCDL packages include a local component repository. Similarly to the CMSIS Pack repository, this is a local folder structure where installed packages are located. The component framework comes with an administration tool that allows new packages or new versions of a package to be installed, old packages to be removed, and so on. Each package has its own little directory hierarchy within the component repository. Keeping several packages in a single directory is illegal. There are no strict rules defining where new packages should get installed.
To better accommodate the package separation for multi-vendor cases, the local folder hierarchy start with a folder with the vendor name.
Packages/ ├── ARM ├── Keil ├── Nuvoton ├── lwIP └── wolfSSL
Below each vendor there are hierarchies of packages. Unrelated packages are all stored just below the vendor folder.
Packages
├── ARM
│ └── CMSIS
├── Keil
│ ├── ARMCortex_DFP
│ ├── Kinetis_K10_DFP
│ ├── Kinetis_KLxx_DFP
│ ├── MCB1500_BSP
│ ├── MDK-Middleware
│ ├── SAMD21_DFP
│ ├── STM32F0xx_DFP
│ ├── STM32F1xx_DFP
│ ├── STM32F2xx_DFP
│ ├── STM32F3xx_DFP
│ ├── STM32F4xx_DFP
│ ├── STM32L0xx_DFP
│ ├── STM32L1xx_DFP
│ ├── STM32NUCLEO_BSP
│ ├── STM32W1xx_DFP
│ ├── TMPM3_DFP
│ └── V2M-MPS2_CMx_BSP
├── Nuvoton
│ └── NuMicro_DFP
├── lwIP
│ └── lwIP
└── wolfSSL
└── CyaSSL
Remote/archived repositories
The usual method of distributing XCDL packages is via http resources, commonly single archive files.
Individual packages
For individually distributed archived packages, the component framework should be able to manage these files, unpack and add their content to the local component repository.
Git/local development trees
For component developers the usual package life cycle of pack/publish/fetch/unpack is not only useless, but may have a significant impact on the speed of the debug/test cycle.
For these cases it should be possible to directly use local folders where the packages are already unpacked.
Since these development folders are usually linked to revision control systems (like Git), another useful feature for the component framework would be to directly manage remote Git repositories.
TODO: define details
Repository content brief
For each remote repository there is a summary content.xml file enumerating the public packages available on the remote location.
The content.xml files hold the list of installed packages and is managed by the administration tool. The various configuration tools read in these files when they start-up to obtain information about the various packages that have been installed.
Package Versioning
Below each package directory there can be one or more version sub-directories, named after the versions. This is a requirement of the component framework: it must be possible for users to install multiple versions of a package and select which one to use for any given application. This has a number of advantages to users: most importantly it allows a single component repository to be shared between multiple users and multiple projects, as required; also it facilitates experiments, for example it is relatively easy to try out the latest version of some package and see if it makes any difference. There is a potential disadvantage in terms of disk space. However since XCDL packages generally consist of source code intended for small embedded systems, and given typical modern disk sizes, keeping a number of different versions of a package installed will usually be acceptable. The administration tool can be used to remove versions that are no longer required.
Packages/ARM
└── CMSIS
├── 3.20.3
├── 3.20.4
├── 4.1.0
└── current
The version current is special. Typically it corresponds to the very latest version of the package.
All other subdirectories of a package correspond to specific releases of that package. The component frame- work allows users to select the particular version of a package they want to use, but by default the most recent one will be used. This requires some rules for ordering version numbers, a difficult task because of the wide variety of ways in which versions can be identified.
Package contents and layout
A typical package contains the following:
- Some number of source files which will end up in a library. The application code will be linked with this library to produce an executable. Some source files may serve other purposes, for example to provide a linker script.
- Exported header files which define the interface provided by the package.
- On-line documentation, for example reference pages for each exported function.
- Some number of test cases, shipped in source format, allowing users to check that the package is working as expected on their particular hardware and in their specific configuration.
- One or more CDL scripts describing the package to the configuration system.
It is also conventional to have a per-package ChangeLog file used to keep track of changes to that package. This is especially valuable to end users of the package who may not have convenient access to the source code control system used to manage the master copy of the package, and hence cannot find out easily what has changed. Often it can be very useful to the main developers as well.
Any given packages need not contain all of these. It is compulsory to have at least one XCDL file describing the package, otherwise the component framework would be unable to process it. Some packages may not have any source code: it is possible to have a package that merely defines a common interface which can then be implemented by several other packages, especially in the context of device drivers; however it is still common to have some code in such packages to avoid replicating shareable code in all of the implementation packages. Similarly it is possible to have a package with no exported header files, just source code that implements an existing interface: for example an ethernet device driver might just implement a standard interface and not provide any additional functionality. Packages do not need to come with any on-line documentation, although this may affect how many people will want to use the package. Much the same applies to per-package test cases.
The component framework has a recommended per-package folder layout which splits the package contents on a functional basis:
Packages/ARM/CMSIS/current ├── ChangeLog ├── doc ├── include ├── meta │ └── xcdl.xml ├── src └── tests
For example, if a package has an include sub-folder then the component framework will assume that all header files in and below that folder are exported header files and will do the right thing at build time. Similarly if there is doc property indicating the location of on-line documentation then the component framework will first look in the doc sub-folder. This folder layout is just a guideline, it is not enforced by the component framework. For simple packages it often makes more sense to have all of the files in just one directory. For example a package could just contain the files hello.cpp, hello.h, hello.html and xcdl.xml. By default hello.h will be treated as an exported header file, although this can be overridden with the includeFiles property. Assuming there is a doc property referring to hello.html and there is no doc sub-directory then the tools will search for this file relative to the package’s top-level and everything will just work. Much the same applies to hello.cpp and xcdl.xml.
Outline of the build process
TBD
Configurable source code
TBD
Exported header files
TBD
Package Documentation
TBD
Test Cases
TBD
Host-side support
TBD
Making a Package Distribution
TBD
The XCDL package distribution file format
TBD
Preparing XCDL packages for distribution
TBD
Credits
The content of this page is based on Chapter 2. Package Organizaion of The eCos Component Writer’s Guide, by Bart Veer and John Dallaway, published in 2001.
