New donator - thanks, Michael Roach!
[ikiwiki.git] / docs / howtos / howtoporttodragonfly / index.mdwn
index e60df3c..c67bf0f 100644 (file)
@@ -29,9 +29,9 @@ Suppose you would want to modify the application foo/bar from the pkgsrc collect
 
 This will restore the changes previously made, which will be a good starting point for the porting. The bmake command could also be used without options to attempt an immediate first compilation. But you might have to change some files first, like the GNU scripts for example.
 
-Suppose that the foo application of the collection is version 1.0. Let's go into the newly extracted source directory located right here<a name="AEN1" href="#FTN.AEN1">[1]</a>:
+Suppose that the bar application of the collection is version 1.0. Let's go into the newly extracted source directory located right here<a name="AEN1" href="#FTN.AEN1">[1]</a>:
 
-       cd /var/obj/pkgsrc/foo/bar/work/foo-1.0
+       cd /usr/pkgobj/bootstrap/work/pkgsrc/foo/bar/work/bar-1.0
 
 Voilà, your ready! The porting of the source code can now begin.
 
@@ -67,7 +67,7 @@ The first level generation is called bootstrapping (see the Bootstrap section).
 
 When porting an application, it is usually not necessary to regenerate these files and directories. You simply need to adjust the Makefile and configure files. But occasionally, you'll have no other choice. The following sections attempt to give you some leads to follow.
 
-#### Editing configure, config.guess and config.sub
+### Editing configure, config.guess and config.sub
 
 When the script configure is run, it creates settings suitable for the host platform. In cases where DragonFly is not on the list of supported systems, we'll need to add it. 
 
@@ -152,6 +152,7 @@ X Window normally comes with a lib/X11/config directory, which contains macro fi
 As for GNU automake, these macros are used to generate makefiles for the operating system that hosts the X Window System. The normal xmkmf's procedure is to define Imakefile files, then to build the makefiles by running xmkmf. This tool will in turn call imake, which is a C preprocessor interface for the make tool. The tool xmkmf will invoke imake with the appropriate arguments for DragonFly.
 
 When xmkmf is executed with the -a option, it automatically runs make Makefiles, make includes and make depends.
+
 Here's a simple Imakefile example:
 
        BINDIR = /usr/local/bin
@@ -187,7 +188,7 @@ In fact, the method mostly used is probably to try to compile, to correct the co
 
        #if defined(__DragonFly__)
                /* code specific to DragonFly */
-       #elsif
+       #elif
                /* code for other systems */
        #endif
 
@@ -229,16 +230,33 @@ The NetBSD group, which maintains pkgsrc, recommends the use of this definition.
 
 Ideally, a port to DragonFly shall always be at the project level. But realistically, it is faster and easier to modify applications at the pkgsrc level.
 
-Tools for pkgsrc allows you to keep only the patches and some basic information of a package. If you want to use pkgsrc, you'll have to use the tool mkpatches.
+pkgsrc contains the patches and some basic information needed to build a package in the *package directory* (by default `/usr/pkgsrc/<category>/<package>`).
+
+The `pkgtools/pkgdiff` suite of tools helps with creating and updating patches to a package. Extract the source code into the *work directory* (by default `/usr/pkgobj/bootstrap/work/pkgsrc/<category>/<package>/work/`) by invoking
+
+        bmake patch
+
+from the package directory. This fetches the source code if necessary, extracts it and applies any existing pkgsrc patch, saving the unpatched files with a `.orig` extension in the work directory.
+
+To create a new patch, save a copy of the original file with that same `.orig` extension. If it exists, just keep it – do not overwrite or change `.orig` files or your patches will not apply later on! You may choose to use `pkgvi` from the `pkgdiff` suite to automate this.
+
+You can preview the patches using `pkgdiff <file>`. To generate all patches invoke
 
-To use this tool, you need to install the pkgtools/pkgdiff package. As indicated earlier in this document, you first need to either extract an existing package or create and extract your own. Then you must keep the original version of each files modified by making a copy of it with the extension .orig. When changes are complete, you can run mkpatches from the directory, say, /usr/pkgsrc/foo/bar. This action will create a set of patches by using the .orig files previously created as a basis. A new directory will be created, here /usr/obj/pkgsrc/foo/bar/work/.newpatches. You then copy this directory like this:
+        mkpatches
 
-       mkpatches
-       mv patches patches.old
-       cp -Rp /usr/obj/pkgsrc/foo/bar/work/.newpatches patches
-       bmake checksum
+from the package directory (not the work directory!) The new patches will be saved in the `patches/` directory along with backups of the previous patchset. When you are content with the generated patches commit them and update the patch checksums:
 
-The last command, bmake checksum, will regenerate the verification file distinfo. From that moment, you can run bmake clean and rebuild the package at will. If you have any other changes to add, you can remove the package again and repeat these steps.
+        mkpatches -c
+        bmake makepatchsum
+
+You may also revert to the old patches by calling `mkpatches -r`.
+
+Now clean up and try to rebuild your package:
+
+        bmake clean
+        bmake
+
+If you have any other changes to add, you can remove the package again and repeat these steps.
 
 ## Submitting a package in pkgsrc
 
@@ -249,6 +267,7 @@ This section will attempt to give you some minimal guidance on submitting change
 A source code package can be submitted with the gtk-send-pr package (pr=Problem Report), or by visiting the page [NetBSD Problem Report](http://www.netbsd.org/support/send-pr.html). The indications given by the pkgsrc developer's guide in connection with this tool are summarized here:
 
 “In the form of the problem report, the category should be “pkg”, the synopsis should include the package name and version number, and the description field should contain a short description of your package (contents of the COMMENT variable or DESCR file are OK). The uuencoded package data should go into the “fix” field.” ̶  http://www.netbsd.org/docs/pkgsrc/submit.html#submitting-your-package
+
 It is also possible to import new packages in pkgsrc-wip. See [http://pkgsrc-wip.sourceforge.net/](http://pkgsrc-wip.sourceforge.net/) for more information.
 
 ## References
@@ -283,7 +302,7 @@ It is also possible to import new packages in pkgsrc-wip. See [http://pkgsrc-wip
       </td>
       <td align="LEFT" valign="TOP">
         <p>
-          Previously, the work directory was created directly in the directory dedicated to the ported application, under the pkgsrc directory. But to preserve the integrity of these directories and to be able to compile on another volume, the working files have been moved under /usr/obj. The source code located in /usr/src followed the same path.
+          Previously, the work directory was created directly in the directory dedicated to the ported application, under the pkgsrc directory. But to preserve the integrity of these directories and to be able to compile on another volume, the working files have been moved under /usr/pkgobj.
         </p>
       </td>
   </tr>