--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/migrating-from-on.txt	Wed Feb 08 16:47:41 2012 -0800
@@ -0,0 +1,88 @@
+This is a case study of migrating one library (libtecla) from ON to Userland.
+I (JBeck) was able to figure out a fair amount on my own, but had to rely on
+Norm for a great deal more, so thought it would be worthwhile to document what
+we went through, to save others time in the future.
+
+* Initially just four files were needed:
+  * Makefile, which in this case I copied from libsndfile as it seemed to be
+    the closest match.
+  * The license: ON's usr/src/lib/libtecla/THIRDPARTYLICENSE copied verbatim
+    to Userland path components/libtecla/libtecla.license .
+  * The lint library: ON's usr/src/lib/libtecla/common/llib-ltecla copied to
+    Userland path components/libtecla/llib-ltecla .
+  * The package manifest: ON's usr/src/pkg/manifests/library-libtecla.mf,
+    with usr/man/pkg/library-libtecla.man.p5m included, copied to Userland
+    path libtecla.p5m .
+
+* Coming from ON, there were already "Solarified" man pages available, so we
+  specified the "--without-man-pages" configure option in the Makefile, and
+  copied all the man pages from ON's usr/man/man/... to the files/ directory
+  and added this Makefile line, which causes pkgdepend/pkgsend to add the
+  appended directories to their search paths when looking for content:
+
+  PKG_PROTO_DIRS += $(COMPONENT_DIR)/files
+
+* Because one of the man pages (enhance.1) had been translated, and there
+  were thus multiple files with the same name, we tweaked the names of the
+  translated files, and used the tweaked names in the package manifest.  We
+  also added the following to get needed "action.hash" and "mangler.bypass"
+  attributes: the former causes pkgmogrify to take the last part of the file
+  action's path attribute (basename) and set the 'hash' value to the basename
+  so that it can be located at the top level of one of the search directories,
+  while the latter causes the userland-mangler to ignore the file, since as
+  mentioned above these man pages come pre-Solarified, whereas the default
+  for Userland is running a file mangler on some of the files to be packaged.
+  This file mangler adds ATTRIBUTES and NOTES sections to man pages with
+  'stability', 'availability', project and source urls.  It also strips the
+  CDDL from files right now.  More functionality may be added over time.
+
+  <transform file path=usr/share/man/man.+/(.+)$ -> set action.hash %<\1> >
+  <transform file path=usr/share/man/.+$ -> add mangler.bypass true >
+
+* On the package manifest fmri action, ON's macros:
+
+  $(PKGVERS_BUILTON)-$(PKGVERS_BRANCH)
+
+  needed to be changed to comparable Userland macros:
+
+  $(IPS_COMPONENT_VERSION),$(BUILD_VERSION)
+
+* These ON attributes needed to be removed:
+
+  set name=org.opensolaris.version-unlockable value=true
+  set name=variant.arch value=$(ARCH)
+
+* The info.upstream-url attribute value needed to be changed from the hard-
+  coded URL in ON to $(COMPONENT_PROJECT_URL) in Userland.
+
+* These needed to be added (note your actual year and ARC case number should
+  be used instead of "YYYY" and "CCC" respectively):
+
+  set name=org.opensolaris.arc-caseid value=PSARC/YYYY/CCC
+  set name=org.opensolaris.consolidation value=$(CONSOLIDATION)
+
+* The $(ARCH64) macro used by ON needed to be changed to $(MACH64).
+
+* ON's license action:
+
+  license usr/src/lib/libtecla/THIRDPARTYLICENSE \
+      license=usr/src/lib/libtecla/THIRDPARTYLICENSE
+
+  needed to be changed to:
+
+  license libtecla.license license="MIT-like"
+
+  Note that "MIT-like" applies to this library; others will have different
+  values.
+
+* Apparently this is unusual, but libtecla's Makefile structure did not have
+  support for $(DESTDIR), so we had to patch Makefile.in to add it.
+
+* Again this is apparently unusual, but libtecla's Makefile structure had
+  LD_RUN_PATH include the working directory, which resulted in build paths
+  being embedded in the binaries.  So we had to patch Makefile.rules to
+  remove that.
+
+* ldd was showing libthread despite it not being explicitly listed; this
+  turned out to be because Userland sets -mt by default, so we had to unset
+  studio_MT in the Makefile.