Source

To be removed once all major points in this email are covered.

	From: 	  john_owens@yahoo.com
	Subject: 	my first port - how to
	Date: 	10 December 2006 08:48:13 EST
	To: 	  macports-users@lists.macosforge.org

Greetings, I'm attempting to write my first port. Writing the portfile
is not too difficult, as there's lots of good examples. However,
actually making it install is a lot tougher.

I am making it work by:

- adding the portfile in the right place in /opt/local
- changing the portindex file to add the port info manually (and
  making up a number for it)

However, these things seem really kludgey. Is it not possible to
have a local portfile somewhere and install it using a command
line "port" command? That would seem much better, but I can't find
any documentation on how that's done. (For instance, there's a 
local "~/.portsrc" file? but I can't find any docs on it.)

I think this is the sort of thing that really ought to be on the
wiki - the barrier to entry of adding a portfile is really very
high, and a short guide would be helpful. What it should say:

- "So you've written a Portfile. Here's how you test it locally."
  - "Here's how you prevent it from being clobbered when you
     selfupdate."
  - "Here's where you put it if you're testing it locally, and want
    to leave it local for a while."
- "Your Portfile is awesome. It works. Here's how to add it to
  the MacPorts repository."
  - "... and here's how you update it."
- "Your Portfile probably has lots of dependencies. Here's how
  you tell what they are." 
- "Here are naming conventions for ports."

etc.

Especially the first one right now would be very useful for me.

JDO

Comments from boeyms@

I intend to get this written up properly some day, but in the meantime:

Creating and maintaining a local port tree for developing ports

• Create the path at which you wish the local port tree to be rooted; I will call it ${localportpath}.
• Create the paths in which you wish to place your portfiles; they will need to be in the form ${localportpath}/<category>/<portname>. Any patches will be expected to be in ${localportpath}/<category>/<portname>/files.
• Run portindex ${localportpath} (or cd to ${localportpath} and run portindex) to generate the PortIndex so that MacPorts will find the ports; portindex will report whether or not it has errors parsing the Portfiles, so fix them before you continue.
• Add ${localportpath} to ${prefix}/etc/ports/sources.conf before the other sources configured there; as should be documented there, you will need to write it as a URL, i.e. file://${localportpath}.
• It should now all work!

Updating a port when you're not a committer, or when it's not your port

• Set up an account in the MacPorts Trac system if you have not already done so. Follow the "Register" link on any MacPorts page (it appears visually in the top right corner).
• Go to the new ticket page (you will be asked to log in if you have not done so already).
• Fill out the ticket in accordance with the guidelines in the ​MacPorts guide.
• Preview your ticket (you won't be able to change its content after submission, only append to it), and then submit it if you are satisfied.
• Attachments: you can add or replace these after the ticket has been submitted by using the "Attach File" button on the ticket once it has been created.
• Please attach any patch files or new Portfiles rather than pasting them inline; the wiki formatting engine may mangle it otherwise.

Determining the dependencies of a port

• A very useful, though not foolproof, technique is to invoke port with the "-t" flag; this will activate the "trace" mode, in which Macports will tell you, after successfully completing each of the stages it goes through:
  • if it thinks there are any undeclared dependencies at that stage;
  • if it thinks there are any unused dependencies at that stage;
  • if any attempts were made to write to files outside of the "sandbox" areas used for fetching patching, configuring, building, testing and destrooting.
• Some ways in which the trace mode can be fooled are:
  • if you have the sysutils/coreutils port installed, ports that use configure scripts produced by GNU Autoconf will detect and use the "ginstall" or "install" executable that sysutils/coreutils installs into ${prefix}/bin, and trace mode will declare coreutils as an undeclared dependency in the configure stage. This is (almost certainly) false, as the system-provided /usr/bin/install will work just fine.