This chapter explains, step by step, how to create a new package. If you start following these instructions, it is implied that you are becoming a package author and hence need to know more about the release tools. This chapter attempts to describe what you need to know as it goes, but it occasionally makes references to other parts of this manual.
The very first step in creating a package is to decide what you shall name it. A part of deciding the name is also deciding the location in the package hierarchy. If you intend the package to become a part of the official releases, these issues are important and you should consult your project policies and other developers' opinions on these matters. You can be more relaxed when the package is going to be exclusively for your personal use.
The release tools impose some limits on package names. The most important limitation is that all package names must be unique regardless of their location in the package hierarchy. For example, you cannot have two packages Simulation/Graphics and Tracking/Graphics.
There are certain letters you should avoid in the package names. You cannot use shell or make metacharacters such as dollar ($), forward or back quotes (`, ’, "), backslash (\), parenthesis, brackets or braces ((, ), [, ], {, }), colons or semicolons (:, ;), or white space. Neither can you, of course, use slash (/) in the package names since it is the directory separator. Note that CVS, compilers, system utilities and the release tools scripts usually protect themselves against the use of these. However, make will not be able to deal with many of them very well. Even when a shell metacharacter will not hinder make, it is a bad idea to use it as it will inconvenience the developers in everyday work.
Due to how the release tools currently implement a feature called linksets, certain character sequences in package names may end up ambiguous. This is because the tools will map the package name into a linkset name prefix, and the prefixes must be unique. The mapping consists of passing all digits, underscores and the English alphabetic characters unchanged, mapping the plus character (+) to the lowercase letter X (x), and mapping all the other characters to underscores (_). Thus, it would not be possible to have two packages Minuit-C and Minuit_C. It would be possible to have Minuit-C and Minuit_c in a unix-only environment. Windows NT has a case insensitive interpretation of file names and naming of this kind can trigger all sorts of interesting but nevertheless unwanted behaviour.
| [1] | Actually, SRT_OUTPUT takes arguments identically to AC_OUTPUT. For more information, consult the autoconf manual. |
| [2] | You may also need to regenerate the script when the release tools have been updated. The tools' release notes will always tell you whether it is necessary and if so, how to do it. |
| [1] | We will only use relatively simple makefiles here, and in particular we will not use linksets. For more information on them, please refer to Section 15.6, ``Linksets''. |
| [2] | The library will be EM_Event.lib on Windows NT; the name will be remapped automatically by the release tools. |
| [3] | By using linksets it is possible to mention in the PACKAGE file the uses that would otherwise be mentioned in the makefile. In fact, the use declarations in the PACKAGE can be more sophisticated than what is possible to express in the makefiles. In that mode the USES property could even be empty. One would define the LINKSET property instead. |
| [1] | You should always modify the template, not the actual makefile. If you modify the actual makefile, your changes will be wiped out without mercy the next time you run configure or config.status. |
| [1] | As a matter of the fact it is possible to import a directory several times into CVS, with pretty much the right results. However, you should restrict the use of that feature only to importing sources from external sources, never with sources you maintain and modify yourself. Checking out sources from CVS and then re-importing them again is an extremely bad idea. |