Changes between Initial Version and Version 1 of UsingMacPortsQuickStart

Timestamp:

Nov 4, 2006, 8:01:38 AM (18 years ago)

Author:

markd@…

Comment:

--

UsingMacPortsQuickStart

@@ +1 @@
+== Overview ==
+
+This guide is designed to help provide you with a quick start to using DarwinPorts. It will cover installing, updating, and removing open source software from your computer provided via the DarwinPorts infrastructure, in addition to some other important basics.
+
+It is important to understand that DarwinPorts is designed so that all software installed within DarwinPorts is installed to its own self-contained directory (`/opt/local`, by default). Software can be built into this directory without interfering with any Apple-provided services, or OS X in general, tested, and even packaged into an OS X-style disk image for deployment on other systems. Using guides such as [http://www.netmusician.org/wiki/index.php/Build_server_with_DarwinPorts this], DarwinPorts installed open source software can even be used to integrate with or replace Apple's installed versions of this same software without having to give up Apple's GUI controls.
+
+This guide was written by [mailto:joe@opendarwin.org Joe Auty] @ [http://www.netmusician.org NetMusician]
+
+== Adding DarwinPorts to your Terminal's path ==
+
+You can interact with DarwinPorts either using the [http://dpgui.sourceforge.net/ Port Authority] GUI, or using the Terminal. If you choose to use the Terminal, the Terminal needs to know to look in your DarwinPorts directory (i.e. `/opt/local` if you are using the defaults) to find its utilities. If you installed MacPorts using the [wiki:InstallingMacPorts InstallingMacPorts] page then you should be able to open a Terminal window and type:
+
+port
+
+If you get a "command not found" error then your path isn't set right and you must review [wiki:InstallingMacPorts InstallingMacPorts].
+
+
+== Selfupdate ==
+
+The basic syntax for using DarwinPorts is:
+
+`port <command-name>`
+
+where "command-name" is one of the commands, or "targets" that DarwinPorts recognizes. For a list of all DarwinPorts targets, type in man port in your Terminal to read the man page for a complete reference guide to the Port command. We will touch on some important ones here, starting with "selfupdate".
+
+Selfupdate is the command used to automatically download new Portfiles so that your local copy of DarwinPorts is aware of new DarwinPorts software or upgrades to existing software that have been committed to the DarwinPorts infrastructure. Additionally, this command is used to update the DarwinPorts software itself - think of it is a Software Update, like its name suggests.
+
+After installing DarwinPorts, try running a selfupdate to grab all the latest DarwinPorts Portfiles (Portfiles contain information about how to install DarwinPorts software "ports"). You will need to run this command as an administrator, and it requires root access, so you'll need to "sudo":
+
+`sudo port selfupdate`
+
+Running DarwinPorts commands, you can add the `-v` command for more verbose ("v" for "verbose") output if you'd like more detail about what DarwinPorts is attempting to do:
+
+`sudo port -v selfupdate`
+
+If you are a developer and would like even more specific accounting of what DarwinPorts is doing, add the `-d` flag.
+
+== Searching for ports ==
+
+To find out what software is available within the DarwinPorts infrastructure, you can consult the [http://www.darwinports.org/ports Available Ports] page, or run a quick search using DarwinPorts. For instance, if you wanted to search for the PHP language:
+
+`port search php`
+
+This will output a list of results such as the following:
+
+{{{
+phpldapadmin                   net/phpldapadmin 0.9.7.2    A set of PHP-scripts to administer LDAP servers over the webs
+phpbb                          www/phpbb      2.0.18       A PHP-based bulletin board / discussion forum system
+phpmyadmin                     www/phpmyadmin 2.7.0-pl1    A tool written in PHP intended to handle the administration of MySQL over the Web
+py-graphpath                   python/py-graphpath 0.7     small language for ananlysing graph-structured data in Python
+php4                           www/php4       4.4.1        PHP: Hypertext Preprocessor
+php5                           www/php5       5.1.1        PHP: Hypertext Preprocessor
+phpbb                          www/phpbb      2.0.18       A PHP-based bulletin board / discussion forum system
+phpicalendar                   www/phpicalendar 2.0.1      web-based iCal viewer
+phpmyadmin                     www/phpmyadmin 2.7.0-pl2    A tool written in PHP intended to handle the administration of MySQL over the
+Web
+}}}
+
+For more info on a port:
+
+`port info php5`
+
+== Variants ==
+
+You may notice that info on several ports provides a list of Variants. You can also produce this same list using the "variants" target:
+
+`port variants php5`
+
+Variants are options that can be built into your install of the port. If you have ever compiled software by hand, you'll know that these options can be set via configure script arguments (e.g. `./configure --prefix=/opt/local`). It can be confusing to figure out what each variant enables, but if you are confused you can ask the port maintainer or the [http://www.opendarwin.org/mailman/listinfo/darwinports DarwinPorts mailing list]. The variants for PHP 5 include specifying operating system version (overriding what the install will automatically attempt to determine for itself), modules for Apache 1.x, 2.x, and support for MySQL 3.x, 4.x, 5.x, or PostgreSQL. 
+
+== Installing ports ==
+
+To install PHP 5 with support for Apache 2.x and MySQL 5.x, issue the following command:
+
+`sudo port install php5 +apache2 +mysql5`
+
+This command will download, compile, and install the PHP 5 port from the official PHP website with the specified build options. Since it will take a while to build and install several ports including all versions of PHP, you might want to include the `-v` flag so that you have evidence that the build is in progress:
+
+`sudo port -v install php5 +apache2 +mysql5`
+
+You may notice that DarwinPorts will build software that you didn't specifically request. This will occur if the port you originally requested has other ports marked as dependencies. Even if the software already exists without OS X, remember the whole DarwinPorts self-contained design approach. Some recreation of existing software may be necessary to produce a functional self-contained environment. 
+
+== Verifying your install ==
+
+After the build and install is complete, if there were no problems along the way, your port should be added to your port registry. For a complete list of all installed ports:
+
+`port installed`
+
+If you are not seeing your port listed, chances are there were some errors in the install. Please share any error messages you encountered with the DarwinPorts mailing list so that we can commit corrections.
+
+== Upgrading existing ports ==
+
+To list all outdated ports, quickly running a selfupdate will make sure that your list of outdated ports reflects the latest versions available within the DarwinPorts infrastructure. To run a selfupdate:
+
+`sudo port -v selfupdate`
+
+To list all outdated ports:
+
+`port outdated`
+
+To upgrade a particular port:
+
+`sudo port upgrade <portname>`
+
+where command name is the name of the port as listed in the "port outdated" list.
+
+To upgrade all outdated ports:
+
+`sudo port upgrade outdated`
+
+(you can add the `-v` flag following "port" in the above command if you'd like to watch the compiler output).
+
+== What if my port install/upgrade fails? ==
+
+Regardless of whether you include the verbose flag, if there is an error it will be provided. Please send these error messages to the port maintainer, or to the DarwinPorts mailing list. You can search for the port maintainer [http://www.darwinports.org/ports here], and/or subscribe to the list via the instructions provided [http://www.darwinports.org/help here].
+
+== How do I configure my DarwinPorts installed application and start it up for the first time? ==
+
+Many configuration files for non-Aqua software will be located in `/opt/local/etc`. If applicable to your port, you will need to edit your config file in this location in preparation for use. If your config file ends in a suffix containing something like "sample", you may need to rename it to exclude this suffix. The general approach of providing a "template" config file ensures that the config file you have setup will not be overwritten the next time you upgrade your port. In fact, all ports should be designed not to blow away your configuration. If this isn't the case, please contact the port maintainer or send an email to the list.
+
+You will need to consult the documentation for the software you have installed to find out how to manually start and stop it if it includes a daemon that is necessary to be running in order for the software to work.
+
+== How do I set my DarwinPorts installed software to automatically startup at boot? ==
+
+Software that includes a daemon that needs to run in order for the software to work often include a variant to install the hooks necessary for the daemon to automatically start at boot time.  In versions of Mac OS X older than and including 10.3.x, when the appropriate variant is specified the SystemStarter script will be installed. In versions newer than and including 10.4.x, a launchd item will be installed. Please check your SystemStarter or launchctl man pages to learn how to manually invoke these startup scripts so that you can test the starting/stopping of your software without having to reboot your machine. In some cases, using SystemStarter/Launchd may be the only way to manually start/stop the daemon(s).
+
+If your DarwinPorts installed software is intended to replace an Apple-provided service, you should disable it to prevent conflicts. There are several techniques you can use to replace various Apple-provided bits. Please contact the list for further information.
+
+== How do I know when an update is available? Do I have to constantly perform manual checks? ==
+
+Selfupdate is a command that can safely be scheduled to automatically run, as it doesn't actually update your installed software, it just "teaches" DarwinPorts about new updates. Take a look at using crontabs to run your selfupdate. You will probably have to provide the full path to the "port" command in your crontab, i.e.:
+
+`/opt/local/bin/port selfupdate`
+
+You will need to set this crontab for the root user, as normal users cannot perform selfupdates.
+
+You can also run "port outdated" as a scheduled task. By enabling the Postfix mail transport agent (a number of guides and utilities are available in OS X for doing so - this is a very easy task), the output of your crontab jobs will be emailed to you. Creating crontabs for both selfupdates and generating outdated port lists can be very useful in learning about new updates on a regular basis.
+
+== Help! ==
+
+Please see the [http://www.darwinports.org/help Get Help] page on the [http://www.darwinports.org DarwinPorts website] for further help.