1 /*!
2 * ======== IVersion ========
3 * Standard package version number interface
4 *
5 * This interface is part of the SDO Package Standard. Each conformant
6 * package that supplies a version number contains a module named
7 * `Version` that implements this interface. In other words,
8 * @p(blist)
9 * - the package's `package.xdc` file declares `Version` as one of it's
10 * modules
11 * - the package contains a spec for the `Version` module (named
12 * `Version.xdc`) and a header generated from this spec (named
13 * `Version.h`)
14 * - the `Version.xdc` file may optionally be generated from the
15 * `ti/sdoarch/standards/pkg/Version.xdt` template when the package's
16 * build script runs.
17 * @p
18 *
19 * This interface defines a set of values that are used to
20 * @p(nlist)
21 * - informally communicate the "degree" of change between successive
22 * releases of a package,
23 * - provide a "key" that enables the producer to unambigeously identify
24 * the sources (and tools) used to produce the package, and
25 * - enable consumers to easily communicate to producers the version(s)
26 * of the package(s) they are using.
27 * @p
28 */
29 interface IVersion {
30 /*!
31 * ======== MAJOR ========
32 * Major version number
33 *
34 * This number should be changed when major changes in the package
35 * occur. Examples include adding new modules, adding substantial new
36 * features to the algorithm(s).
37 */
38 const UInt16 MAJOR;
39
40 /*!
41 * ======== MINOR ========
42 * Minor version number
43 *
44 * This number should be changed when minor changes in the package
45 * occur. Examples include minor changes to the existing APIs,
46 * adding minor features to the algorithms(s) including expanding the
47 * configuration options.
48 */
49 const UInt16 MINOR;
50
51 /*!
52 * ======== PATCH ========
53 * Patch level
54 *
55 * This number should be changed when bug fixes or performance
56 * improvements are introduced. There should be no changes in the APIs
57 * in this case.
58 */
59 const UInt16 PATCH;
60
61 /*!
62 * ======== WIDTH ========
63 * Minimum width of print fields
64 *
65 * When denoting version numbers using '.' to separate fields
66 * there is a danger of confusing version "6.1" and version "6.10";
67 * because, in decimal notation 6.1 == 6.10. To avoid
68 * this confusion, it is common practice to adopt a fixed minimum field
69 * width that's when printing version dimensions (other than MAJOR);
70 * e.g., rather than printing "6.1", if WIDTH == 2 then the version would
71 * be displayed as "6.01".
72 */
73 const UInt16 WIDTH;
74
75 /*!
76 * ======== getString ========
77 * Returns a string representation of the version
78 *
79 * This method return a string of the form:
80 * @p(code)
81 * MAJOR<sep>MINOR<sep>PATCH
82 * @p
83 * where `MAJOR`, `MINOR`, and `PATCH` are
84 * the values sepcified in this interface and `<sep>` is the (optional)
85 * argument to this method. If `separator` is not supplied (or is
86 * `null`), `<sep>` defaults to `'.'`.
87 */
88 function getString(separator);
89 }
90
91