====== Pkgsrc Guide ======

<div round info>
**Stale page**

This guide refers to an unofficial pkgsrc mirror on github which appears to have fallen out of date. The official git.minix3.org repositories should be used instead. The instructions need to be updated.
</div>

===== About =====

MINIX uses [[http://pkgsrc.org/|pkgsrc]] to [[http://en.wikipedia.org/wiki/Porting|port]] and maintain packages of third-party software. This guide will introduce you to the basics.

===== Getting started =====

1. [[.:trackingcurrent|Update]] MINIX periodically

2. [[:usersguide:installingsourcepackages|Learn]] about pkgsrc

===== Going online =====

1. [[https://github.com/|Create an account]] and [[http://help.github.com/set-up-git-redirect|add SSH keys at GitHub]]

2. <del>[[http://help.github.com/fork-a-repo/|Fork]] the MINIX 3 [[https://github.com/minix3/pkgsrc/|pkgsrc repository]] on GitHub</del> You should clone the official repository from git.minix3.org instead. Please update these instructions.

 <del>This makes your repositories similar, so that updates will be quick.</del>

===== Setting up =====

1. Download your pkgsrc repository

 First, download the official pkgsrc.

<code>
cd /usr

make pkgsrc
 
</code>

 Then, add your remote repository.

<code>
cd /usr/pkgsrc

git remote add me git@github.com:you/pkgsrc.git
 
</code>

2. Create your minix-master branch

<code>
git fetch me

git branch my-minix-master me/minix-master
 
</code>

3. Check-out your minix-master branch locally

<code>
git checkout my-minix-master
 
</code>

===== Starting to port a package =====

Found something in pkgsrc that you want to port to MINIX?

  - Create a new branch from it to host your work

<code>
git checkout -b my-package
 
</code>

  - Install package tools

<code>
# cd /usr/pkgsrc/pkgtools/pkgdiff
# bmake install
 
</code>

 This installs several tools we'll be using.

===== Making changes =====

  - Get the package ready for editing

<code>
cd /usr/pkgsrc/[category]/[package]

bmake patch
 
</code>

 This applies patches, but doesn't build. Build results aren't usable for patches.

  - Go to the package's work directory

<code>
cd /usr/pkgsrc/work/[category]/[package]/work/[package name]
 
</code>

  - Edit files

<code>
pkgvi somefile.c
 
</code>

 Use //EDITOR=nano pkgvi// to use GNU nano instead of nvi.

  - Go to the package directory

<code>
cd /usr/pkgsrc/[category]/[package]
 
</code>

  - Make patches

<code>
mkpatches

rm patches/*.orig
 
</code>

  - Make checksums

<code>
bmake makepatchsum
 
</code>

  - Test your changes

<code>
bmake clean

bmake
 
</code>

  - Save your work

<code>
cd /usr/pkgsrc/[category]/[package]

git add distinfo patches

git commit
 
</code>

The commit message should provide a summary of the change. The first line of the commit message should be in the form "[category]/[package]: summary of change." Example: "print/ghostscript: add missing bsd.prefs.mk include". If it's a complex change, the commit message should provide additional explanation.

===== Putting it online =====

Push this branch to your remote repository.

<code>
git push me my-package
 
</code>

 This will let others test your changes and later include them in pkgsrc.

===== Telling people about it =====

 When your branch is ready, let people know by posting to the Google Group.

 Here's an example:

<code>
Subject: [package] Ported

Hi,

I've ported [package], and my branch "my-package" is ready for testing at: https://github.com/[me]/pkgsrc.git

Thanks
 
</code>

 When the MINIX team agrees that the package changes in your GitHub repository, they will copy the changes into MINIX's pkgsrc repository.

===== Updating your changes =====

As changes in MINIX's pkgsrc repository become available, updating your repository allows your changes to merge cleanly in the future.

1. Update the official branch

<code>
git checkout minix-master

cd /usr

make pkgsrc-update
 
</code>

2. Make your minix-master branch identical to the official one

<code>
cd /usr/pkgsrc

git checkout my-minix-master

git rebase minix-master
 
</code>

3. Merge changes from either the official into your own

<code>
git checkout my-package-port

git merge my-minix-master
 
</code>

4. Push your local branch up to your repository

<code>
git push me my-package
 
</code>

===== Problems? =====

==== Stuck or confused? ====

Please do your best to let people know what's happening. If you're having trouble or have an idea, then please tell someone.

The IRC channel and the Google Group are the best places for talking with the rest of the community.

==== Need to use https:// instead of git://? ====

If you use HTTPS and have an SSL-related problem when you fetch, then please use the following steps to install SSL certificates.

<code>
cd /usr/pkgsrc/security/mozilla-rootcerts

bmake install

cd /usr/pkg/etc/openssl/certs

mozilla-rootcerts extract

mozilla-rootcerts rehash
</code>

===== Resources =====

If you'd like to learn more about pkgsrc or need help, there are good places to go [[:resources|on this page]].