Instructions for binding the Alesis E-Practice Pad

The FreeBSD Porter Handbook


Configuring the is very simple and we suggest that you first take a look at existing examples. Additionally there is an example of a Makefile in this manual. Have a look and please keep track of the sequence of variables and sections in this template. This will make it easier for others to read your port.

Please consider the following problems in the sequence of the subsections of this chapter given here when creating your new one:


5.1. The original source code

Is the source code in the form of a standardized file packed with gzip? If so, you can move on to the next step. If not, you should try changing the variables,,,,,, or. That depends on how strange your port's distribution file is (the most common case is when the tarball was packed by a normal one and not by).

In the worst case, you can simply create your own default using and overwrite the default; but this should in the least, if ever, be necessary.


5.2. Designations

The first part of describes the version number of the port and lists it in the correct category.


5.2.1. and

Please set the variable to the base name of your port and the variable to its version number.


5.2.2. and

5.2.2.1.

The variable is a strictly monotonically increasing value which is reset to 0 after it has been increased (i.e. every time an official release takes place). It is appended to the name of the package if it is not equal to 0. Changes to are used by automated tools (e.g. pkg_version (1)) to indicate that a new package is available.

should be increased each time a change is made to the port that has a significant impact on the content or structure of the packet generated from the port.

Examples of when to increase:

  • Adding patches that close security gaps, fix bugs or add new functionality to the port.

  • Changes to the port, which compile-time options add or remove.

  • Changes to the packing list or to the behavior during the installation of the package (i.e. changes to a script that generates output data for the package, such as SSH host key).

  • Version jump of a shared library, which is a dependency of this port (in this case a user would fail to install the old package if he has already installed a new version of the dependency, because according to the old library libfoo.x instead of libfoo. (x + 1)) is searched).

  • Gradual changes to the distfile, which cause significant functional changes, i.e. changes to the distfile require a correction without the associated change, although a significant change to the code between the old and the new version proves.

Examples of changes that do not require an increase in:

  • Stylistic changes to the basic structure of the port without functional changes to the resulting package.

  • Changes to the variable or other functional changes that do not change the resulting package.

  • Marginal patches to the distfile, such as the correction of typographical errors, which are not important enough to impose the burden of an upgrade on the user.

  • Build fixes that first make a package compilable, which could not be created without these changes (as long as the changes do not result in a functional difference on platforms on which this package could already be built before). As the content of the package reflects, it is not necessary to increase if the package could not be created beforehand.

As a rule of thumb, ask yourself whether the change you have made to the port will help everyone (either due to an improvement, a bug fix, or the assumption that the new package will work in the first place) and weigh it against the fact that anyone who regularly keeps their ports collection up to date is forced to update it. If you answer affirmatively, increase the variable.


5.2.2.2.

From time to time someone (third party software vendor or FreeBSD ports committer) does something stupid and releases a version of software with a version number lower than the previous one. An example of this is a port that is changed from foo-20000801 to foo-1.0 (the former is mistakenly treated as a new version because 2000801 is a numerically greater value than 1).

In situations like this, the variable should be increased. If greater than 0, it is appended to the name of the package, as described in section 0 above. must never be reduced or set to 0 because the comparison of the package with an earlier point in time would fail (i.e. the package would never be recognized as out of date): The new version number (in the example above) is still numerically smaller than the previous version ( 2000801), but the suffix is ​​treated separately by automated tools and is recognized as larger than the implicitly assumed suffix in the earlier package.

Removing or resetting leads to endless hassle. If you have not fully understood the above, please read it again until you have completely internalized it, or ask on the mailing lists before making any changes!

It is expected that the vast majority of the ports will not be used and the responsible and forward-looking approach will usually make it superfluous if a later release should change the version structure. Caution is advised when a release of third-party software is released without an official version number, such as `` snapshot versions ''. One is tempted to name the release with the respective date, which inevitably leads to the problems described above when the next `` official '' release appears.

For example, if a snapshot is published on the date 20000917 and the previous version of the software was 1.2, then the snapshot should get 1.2.20000917 or similar and not 20000917 so that the subsequent release, say 1.3, still has a larger numerical value.


5.2.2.3. Example of the use of and

The port, version, is in the Ports Collection:

PORTNAME = gtkmumble PORTVERSION = 0.10

becomes .

A security hole has been discovered that requires a local patch from FreeBSD. is increased accordingly.

PORTNAME = gtkmumble PORTVERSION = 0.10 PORTREVISION = 1

becomes

A new version is released by the third party software vendor, labeled Version (it turns out the author intended that should mean, not `` what's after 0.9 '' - oops, but it's too late now). Since the new minor version is numerically smaller than the previous version, it must be increased to ensure that the new package is also recognized as `` newer ''. Since it is a new release from the third party, it will be reset to 0 (or removed from the).

PORTNAME = gtkmumble PORTVERSION = 0.2 PORTEPOCH = 1

becomes

The next release is 0.3. Since there is never a decrease, the version variables are now as follows:

PORTNAME = gtkmumble PORTVERSION = 0.3 PORTEPOCH = 1

becomes

Annotation: If this upgrade had reverted to, then someone who installed the package would not recognize the package as new because is still numerically less than. Remember that this is exactly the whole point.


5.2.3. and

Two optional variables, and, are combined with and to form as. Please make absolutely sure that these variables comply with the guidelines for a good package name. In particular, you are allowed to by no means use a hyphen () in. If the package has the or part (see below) use or respectively. Do not make these variables part of!


5.2.4.

In some cases several versions of an application can be in the ports collection at the same time. The index build and package build systems must now be able to recognize them as different ports, although these versions all have the same variables, and even. In such cases, the optional variable should be set to a different value for all ports with the exception of the `` main port ''. Examples are the and ports and the family. Please note that the question of selecting the `` most important '' version (`` most popular '', `` best supported '', `` last patched '' etc.) is beyond the scope of this manual. We're just telling you how to specify the other ports after you've chosen the `` main port ''.


5.2.5. Naming rules for packages

Below are the rules for naming your packages. These are supposed to ensure that the package directory is easy to search, as there are already thousands upon thousands of packages and users will turn away with a shudder when their eyes are strained!

The package name should look like.

The package name is defined as. Please make sure that the variables of your port correspond to this format.

  1. FreeBSD goes to great lengths to support the national languages ​​of its users. The variable should be an abbreviation with 2 letters of the languages ​​according to ISO-639, if the port is specific for a certain language. Examples are for Japanese, for Russian, for Vietnamese, for Chinese, for Korean and for German.

    If the port is specific for a certain region within a language area, please also add the country code with 2 letters. Examples are for North American English and for Swiss French.

    The part must be set in the variable.

  2. The first letter of the -part must be written in lower case (the rest of the name can contain upper case letters, so please be careful when converting the name of software that contains upper case letters). It is a tradition to denote modules with a preceding one and by converting the double colon into hyphens. For example, the module becomes the port.

  3. Make sure that the name of the port and its version number are clearly separated and are in the variables and. The only reason to include in a version part is that the software is really named like the ports or. Otherwise it should not have any version-specific components. It is perfectly normal for many ports to have the same features as e.g. the ports. In this case, different versions (and different index entries) are distinguished by the values ​​of, and.

  4. If the port can be built with different, hard-coded specifications (usually part of the directory name in a family of ports), then the -part should display the compiled specifications (the hyphen is optional). Examples of this are paper sizes and font units.

    The part must be set in the variable.

  5. The version string should end with a hyphen () and be a period-separated list of integers and lowercase letters. It is not permitted to use another hyphen within the version string! The only exception to this is the string (meaning `` patchlevel ''), which just may be used if the application has no major or minor version numbers. If the version designation of the software contains character strings such as `` alpha '', `` beta '', `` rc '' or `` pre '', please take the first letter from it and put it immediately after a period. If the version string continues after this period, the numbers should follow without a period between each letter.

    The goal is to sort the ports based on the version string. Please make absolutely sure that the components of the version number are always separated by a period and, if dates are used, these are in the format and not or not at all in the Y2K-compatible format.

Here are some real world examples showing how to convert an application name to a reasonable package name:

Software namereason
mule-2.2.2(empty)mule(empty)2.2.2No change required
EmiClock-1.0.2(empty)emiclock(empty)1.0.2no capital letters for individual applications
rdist-1.3alpha(empty)rdist(empty)1.3.aNo strings as allowed
es-0.9-beta1(empty)it(empty)0.9.b1no strings as allowed
mailman-2.0rc3(empty)mailman(empty)2.0.r3no strings as allowed
v3.3beta021.src(empty)tiff(empty)3.3What should that actually be?
tvtwm(empty)tvtwm(empty)pl11Version string is mandatory
piewm(empty)piewm(empty)1.0Version string is mandatory
xvgr-2.10pl1(empty)xvgr(empty)2.10.1 only allowed if no version number is available
gawk-2.15.6Yes-gawk(empty)2.15.6Japanese language version
psutils-1.13(empty)psutils-letter1.13Fixed coded paper size when building a package
pkfonts(empty)pkfonts3001.0Package for 300 DPI fonts

If there is absolutely no indication of any version designation in the original source and it is unlikely that the author will ever publish a new version, then please simply set up the version (as in the example above). You can also ask the author or use a date string () as the version.


5.3. Categorization

5.3.1.

When a package is created it is placed under and links are created from one or more subdirectories. The names of these subdirectories are determined by the variable. This is done to help the user browse a large number of packages on an FTP website or CD / DVD. Please take a look at the current list of categories and choose the best category for your port.

This list also determines where the port is inserted in the ports collection. If you specify several categories, it is assumed that the port files are located in the subdirectory with the name of the first category specified. Please see below for more information on how to determine the correct category.


5.3.2. Current list of categories

Here is the current list of categories. Those marked with an asterisk () are virtual Categories, i.e. those that do not have their own subdirectory in the ports collection. They are only used as secondary categories and have been set up for search purposes only.

Annotation: For non-virtual categories you will find a one-line description in the variable in the respective subdirectory.

categorydescriptionannotation
Ports for disabled people. 
Ports for the AfterStep Window Manager. 
Arabic language support. 
Archiving tools. 
Ports for astronomy. 
Sound support. 
Benchmarking tools. 
Software for biology. 
CAD tools. 
Chinese language support. 
Communication programs.Mainly software for serial interfaces.
Character set converter. 
Databases. 
Things that were on the desk before the computer was invented. 
Development tools.Don't put libraries here just because they are libraries unless they really don't belong anywhere else.
DNS-related software. 
Meta ports for FreeBSD documentation. 
general editors.Special editors belong in their respective category (e.g. a mathematical formula editor belongs in).
Emacs lisp ports. 
Emulators for other operating systems.Terminal emulators include Not here; X-based ones belong to and text-based ones belong to or, depending on their exact functionality.
Financial software and the like. 
French language support. 
FTP client and server tools.If your port supports both FTP and HTTP, set it in with the second category.
Games. 
geographic software. 
German language support. 
Ports for GNOME 
Software for GNUstep. 
graphic tools. 
Ham radio software. 
Software for the Haskell programming language. 
Hebrew language support. 
Hungarian language support. 
IPv6-related software. 
Internet Relay Chat (IRC) tools. 
Japanese language support. 
Java ™ programming language software.The category should not be the only one for a port with the exception of the applications that are directly related to the programming language. Porters should not be chosen as the main category of a port.
Ports for the K Desktop Environment (KDE) project. 
Kernel modules. 
Korean language support. 
Programming languages. 
Linux applications and tools. 
Software for the Lisp programming language. 
Mail software. 
Numerical calculations and other math tools. 
MBone applications. 
Different tools.Mainly tools that don't belong elsewhere. If at all possible, try to find a better category for your port than because ports are easily drowned out here.