= Migrating a MacPorts installation =

A MacPorts installation is designed to work with a particular operating
system and a particular hardware architecture. Problems may occur
after major system changes, such as:
- major operating system upgrades (e.g., from 10.9 Mavericks to 10.10
  Yosemite).
- architecture migrations (e.g., from PowerPC to Intel).
- migrations from one computer to another
Please follow this procedure to ensure a smooth transition. (This isn't
necessary if you only upgrade Xcode.)

== Migration procedure ==

1. [=#assistant **Migration Assistant**]

   If you are going to use the Migration Assistant to copy files and/or settings from an old computer to a new one, do so now.


2. [=#xcode **Install the latest version of Xcode and the Xcode command line tools**]

   After a major system change, update the development tools by
   [https://guide.macports.org/#installing.xcode installing the latest version of Xcode].
   Open the Xcode application once after installation and follow any prompts.
   Install the command line tools package as well (run `xcode-select --install`).

3. [=#base **Reinstall MacPorts base**]

   After updating the development tools,
   [https://www.macports.org/install.php install the base MacPorts system]
   for your new platform, either from the appropriate installer or from
   source.

   **Update macports.conf**: If your {{{macports.conf}}} (typically at {{{ /opt/local/etc/macports/macports.conf}}}) contains uncommented settings for {{{universal_archs}}} or {{{build_arch}}}, you will likely want to update them, since unlike earlier OS versions, the compiler on Snow Leopard and later will build for x86_64 by default on systems that support it. The default values will be fine for almost all users, so unless you know you need something different, just comment out these two lines. Several other settings in {{{macports.conf}}} have changed their defaults over the years. Take a moment to compare each line of your {{{macports.conf}}} with the corresponding line in {{{macports.conf.default}}} in the same directory. Unless you know a reason why a line in your settings file should be different from the defaults, adopt the line from the defaults file.

4. [=#ports **Reinstall ports**]
   a. Save the list of installed ports:
      {{{
      port -qv installed > myports.txt
      }}}
   a. (optional) Save the list of requested ports:
      {{{
      port echo requested | cut -d ' ' -f 1 > requested.txt
      }}}
   a. Uninstall all installed ports:
      {{{
      sudo port -f uninstall installed
      }}}
   a. Clean any partially-completed builds:
      {{{
      sudo rm -rf /opt/local/var/macports/build/*
      }}}
   a. Download and execute the restore_ports script. (If you installed MacPorts from source and used a custom prefix, then you'll need to use the -p option when you run restore_ports.tcl; see `./restore_ports.tcl -h`.)
      {{{
      curl --location --remote-name https://github.com/macports/macports-contrib/raw/master/restore_ports/restore_ports.tcl
      chmod +x restore_ports.tcl
      sudo ./restore_ports.tcl myports.txt
      }}}
      Note: ports that are not available on your new platform will be skipped without error.
   a. (optional) Restore requested status:
      If you saved the list of requested ports, you can now restore the requested flags for your newly installed ports to their former states.
      {{{
      sudo port unsetrequested installed
      xargs sudo port setrequested < requested.txt
      }}}
      Warning: if a port in `requested.txt` was ''not'' installed in the previous step, the iterative `setrequested` will terminate, leaving some ports still marked as not-requested. Edit `requested.txt` to remove any ports that were not installed and repeat this step. Double check your desired ports are set as requested with `port echo requested`.

== Troubleshooting ==

Though it is now quite well-tested, the restore_ports script may fail in some cases. One known issue is that the script will fail if there are conflicting ports in the list. It's possible to have conflicting ports installed provided at most one of the conflicting set is active. If the script fails for this reason, you can delete one of the conflicting ports from myports.txt and then simply run the script again. You may need to do this multiple times if there are multiple conflicting ports listed.

In the worst case, you can reinstall your ports manually by browsing `myports.txt` and installing the ports one by one, remembering to specify the appropriate variants:
{{{
sudo port install portname +variant1 +variant2 …
}}}
Note that if you have specified variants which are not the default, you may need to install ports in an order other than the alphabetical order recorded in `myports.txt`. You may skip explicitly installing ports that you did not request as long as they are not using non-default variants, since they will be installed as dependencies of other ports.

If things go really wrong, don't forget that you can always [https://guide.macports.org/chunked/installing.macports.uninstalling.html uninstall MacPorts] entirely before manually reinstalling ports.

Another potential problem is that the `restore_ports.tcl` command may fail with a `Too many open files` error message. Under macOS Sierra, the default shell has a default `ulimit` of 256 open files. The solution is to restore the ports with a slightly modified command:
{{{
sudo bash -c "ulimit -n 4096; ./restore_ports.tcl myports.txt"
}}}
This will raise the file limit for the duration of the `restore_ports.tcl` command.