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