doc/migrating-from-on.txt

   1 This is a case study of migrating one library (libtecla) from ON to Userland.
   2 I (JBeck) was able to figure out a fair amount on my own, but had to rely on
   3 Norm for a great deal more, so thought it would be worthwhile to document what
   4 we went through, to save others time in the future.
   5
   6 * Initially just four files were needed:
   7   * Makefile, which in this case I copied from libsndfile as it seemed to be
   8     the closest match.
   9   * The license: ON's usr/src/lib/libtecla/THIRDPARTYLICENSE copied verbatim
  10     to Userland path components/libtecla/libtecla.license .
  11   * The lint library: ON's usr/src/lib/libtecla/common/llib-ltecla copied to
  12     Userland path components/libtecla/llib-ltecla .
  13   * The package manifest: ON's usr/src/pkg/manifests/library-libtecla.mf,
  14     with usr/man/pkg/library-libtecla.man.p5m included, copied to Userland
  15     path libtecla.p5m .
  16
  17 * Coming from ON, there were already "Solarified" man pages available, so we
  18   specified the "--without-man-pages" configure option in the Makefile, and
  19   copied all the man pages from ON's usr/man/man/... to the files/ directory
  20   and added this Makefile line, which causes pkgdepend/pkgsend to add the
  21   appended directories to their search paths when looking for content:
  22
  23   PKG_PROTO_DIRS += $(COMPONENT_DIR)/files
  24
  25 * Because one of the man pages (enhance.1) had been translated, and there
  26   were thus multiple files with the same name, we tweaked the names of the
  27   translated files, and used the tweaked names in the package manifest.  We
  28   also added the following to get needed "action.hash" and "mangler.bypass"
  29   attributes: the former causes pkgmogrify to take the last part of the file
  30   action's path attribute (basename) and set the 'hash' value to the basename
  31   so that it can be located at the top level of one of the search directories,
  32   while the latter causes the userland-mangler to ignore the file, since as
  33   mentioned above these man pages come pre-Solarified, whereas the default
  34   for Userland is running a file mangler on some of the files to be packaged.
  35   This file mangler adds ATTRIBUTES and NOTES sections to man pages with
  36   'stability', 'availability', project and source urls.  It also strips the
  37   CDDL from files right now.  More functionality may be added over time.
  38
  39   <transform file path=usr/share/man/man.+/(.+)$ -> set action.hash %<\1> >
  40   <transform file path=usr/share/man/.+$ -> add mangler.bypass true >
  41
  42 * On the package manifest fmri action, ON's macros:
  43
  44   $(PKGVERS_BUILTON)-$(PKGVERS_BRANCH)
  45
  46   needed to be changed to comparable Userland macros:
  47
  48   $(IPS_COMPONENT_VERSION),$(BUILD_VERSION)
  49
  50 * These ON attributes needed to be removed:
  51
  52   set name=org.opensolaris.version-unlockable value=true
  53   set name=variant.arch value=$(ARCH)
  54
  55 * The info.upstream-url attribute value needed to be changed from the hard-
  56   coded URL in ON to $(COMPONENT_PROJECT_URL) in Userland.
  57
  58 * These needed to be added (note your actual year and ARC case number should
  59   be used instead of "YYYY" and "CCC" respectively):
  60
  61   set name=org.opensolaris.arc-caseid value=PSARC/YYYY/CCC
  62   set name=org.opensolaris.consolidation value=$(CONSOLIDATION)
  63
  64 * The $(ARCH64) macro used by ON needed to be changed to $(MACH64).
  65
  66 * ON's license action:
  67
  68   license usr/src/lib/libtecla/THIRDPARTYLICENSE \
  69       license=usr/src/lib/libtecla/THIRDPARTYLICENSE
  70
  71   needed to be changed to:
  72
  73   license libtecla.license license="MIT-like"
  74
  75   Note that "MIT-like" applies to this library; others will have different
  76   values.
  77
  78 * Apparently this is unusual, but libtecla's Makefile structure did not have
  79   support for $(DESTDIR), so we had to patch Makefile.in to add it.
  80
  81 * Again this is apparently unusual, but libtecla's Makefile structure had
  82   LD_RUN_PATH include the working directory, which resulted in build paths
  83   being embedded in the binaries.  So we had to patch Makefile.rules to
  84   remove that.
  85
  86 * ldd was showing libthread despite it not being explicitly listed; this
  87   turned out to be because Userland sets -mt by default, so we had to unset
  88   studio_MT in the Makefile.