*-devel ports

[Ryan Schmidt]

The guide needs to say something (quite a lot, actually) about *- 
devel ports. The only thing it currently says is:

"Non-port dependencies should only be used if the application or  
library can be installed by multiple ports (for example stable and - 
devel version) or if it can't be installed with MacPorts."

There's a lot of room for confusion with the *-devel ports so it  
needs to be properly documented. I want to file a ticket for this  
request, but before I do, we should make sure we know what we want  
the guide to say about the topic. Let me just ramble for a bit on how  
I think *-devel ports work and how they should be used. Maybe someone  
with an official hat on can respond and say where I've got it right  
or wrong.


*-DEVEL PORTS
=============

Some ports may have a development version available, which installs a  
pre-release version of the software, instead of a stable version. The  
name of such a port will end with the suffix "-devel", so for example  
the port php5 installs the latest released version of PHP 5 while  
php5-devel installs a development, alpha, beta or release candidate  
version. Most users will not need to use -devel ports, but if the  
latest stable version does not include a feature or bugfix that you  
need, and the latest development version does, you may want to use  
the -devel port instead.

Warning: -devel ports by definition install software which is not  
necessarily of release quality and has not necessarily been  
exhaustively tested. Software installed by -devel ports may not work  
properly and should not be used in production systems.

Note: MacPorts uses -devel ports for an entirely different purpose  
than some other package managers (e.g. Linux? FreeBSD? not sure). In  
those other package managers, a port foo-devel would contain the  
headers necessary for other software to link with foo. But in  
MacPorts, these headers are already part of the foo port.

To create a -devel port, copy the regularly-named port and change it  
minimally to install the development version instead. Always keep the  
two ports as similar as possible. If you fix a bug, add a feature or  
make formatting changes in one port, don't forget to make the same  
changes in the other port.

So that the ports can be kept similar, it's best if the regular port  
and the -devel port are maintained by the same person. Or, two  
developers can co-maintain both ports. If you would like to create  
and maintain a -devel version of a port which is maintained by  
someone else, coordinate with the other maintainer first. Invite them  
to co-maintain your -devel port, and ask if you can co-maintain their  
port.

A -devel port should install software into the exact same locations  
as the regularly-named port. Thus, it is not possible to install both  
foo and foo-devel at the same time. You must pick one or the other.

Sometimes a port foo-devel will install a newer version of the  
software than foo, and this is a reason why you might want to use the  
port foo-devel, to test a new version of the software before it's  
released. However, after the new version is released, foo will be  
installing a newer version of the software than foo-devel. If you  
have foo-devel installed, you will not be notified if and when a  
newer version is provided by foo. To get that newer version, you will  
need to uninstall foo-devel and install foo. (I don't especially like  
all this, but this is the way it is, so this is the way it should be  
documented. Changing this behavior should be the topic of a separate  
discussion.)

No port should depend on a -devel version of a port, unless it will  
only work with the -devel version. Usually this will not be the case.  
Usually, a port will work with the current version of a port and the  
latest development version. A port wanting to accommodate this  
situation should use a different syntax for declaring the dependency.  
For example, php5 can use the MySQL libraries, but works fine with  
either mysql5 or mysql5-devel. Instead of declaring the dependency as  
"port:mysql5", php5 should depend on a specific file installed by  
both mysql5 and mysql5-devel, like this: "path:${prefix}/bin/ 
mysql_config5:mysql5". This says that php5 requires the file  
mysql_config5 to exist in the MacPorts install prefix bin directory,  
and if it does not exist, then install the mysql5 port. If the user  
wishes to use mysql5-devel instead, he simply installs mysql5-devel  
beforehand, then installs php5, and php5 will recognize that mysql5- 
devel satisfies the dependency. (I know php5 does not do this yet;  
this is ticket #13469.)