== 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 [/newticket 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 [http://guide.macports.org/chunked/project.html 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.