doc/makefile-variables.txt
author Mike Sullivan <Mike.Sullivan@Oracle.COM>
Fri, 07 Apr 2017 17:56:36 -0700
changeset 7851 f82a18f72950
parent 7835 20c33a4fd225
permissions -rw-r--r--
Close of build 122.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1245
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
     1
This is a guide to explain various useful variables in Userland component
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
     2
Makefiles.  To distinguish these from the Makefile(s) that are part of each
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
     3
component distribution, the latter will be referred to as native Makefiles.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
     4
6911
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
     5
The following are the basics that just about every Makefile should have.  Most
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
     6
have defaults, but can be overridden.
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
     7
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
     8
* BUILD_ARCH declares which architecture this component should be built for;
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
     9
  possible values are: i386, sparc.  If not set, the component will be built
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    10
  for both.
5682
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    11
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    12
* BUILD_BITS declares which bits this component should be built for and
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    13
  which binaries are the preferred ones (i.e. should be installed in /usr/bin);
6911
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    14
  values are: 64, 64_and_32, 32, 32_and_64, and NO_ARCH.
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    15
1245
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    16
* COMPONENT_NAME is typically a short name (e.g., vim).
6911
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    17
1245
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    18
* COMPONENT_VERSION is typically numbers separated by dots (e.g. 7.3).
6911
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    19
5682
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    20
* COMPONENT_SRC is where the archive is extracted; it has a default value of
1245
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    21
  "$(COMPONENT_NAME)-$(COMPONENT_VERSION)".
6911
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    22
1245
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    23
* COMPONENT_PROJECT_URL is the general web site for the component.
6911
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    24
5682
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    25
* COMPONENT_ARCHIVE is the base name of the archive to be downloaded; it has
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    26
  a default value of "$(COMPONENT_SRC).tar.gz".
6911
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    27
1245
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    28
* COMPONENT_ARCHIVE_HASH is typically "sha256:" followed by the first output
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    29
  field of `sha256sum $(COMPONENT_ARCHIVE)`.
6911
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    30
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    31
* COMPONENT_ARCHIVE_SRC defines what kind of object delivers the source.  This
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    32
  can be "git", "hg", or "svn" if the source comes from an SCM repository, and
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    33
  must be "none" if the source is checked into the Userland repository
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    34
  directly.
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    35
1245
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    36
* COMPONENT_ARCHIVE_URL is where the archive can be downloaded from.  This is
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    37
  typically constructed from $(COMPONENT_PROJECT_URL) and $(COMPONENT_ARCHIVE).
6911
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    38
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    39
* COMPONENT_BUGDB is the lower-case rendering of the BugDB cat/subcat; it has
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    40
  a default value of "utility/$(COMPONENT_NAME)".
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    41
7687
1093e2a9adbd 25590368 Userland components should include "upstream" release tracking information
Rich Burridge <rich.burridge@oracle.com>
parents: 6911
diff changeset
    42
* COMPONENT_ANITYA_ID is the project id for this software at
1093e2a9adbd 25590368 Userland components should include "upstream" release tracking information
Rich Burridge <rich.burridge@oracle.com>
parents: 6911
diff changeset
    43
  https://release-monitoring.org which is used to track when a new version
1093e2a9adbd 25590368 Userland components should include "upstream" release tracking information
Rich Burridge <rich.burridge@oracle.com>
parents: 6911
diff changeset
    44
  is available.
1093e2a9adbd 25590368 Userland components should include "upstream" release tracking information
Rich Burridge <rich.burridge@oracle.com>
parents: 6911
diff changeset
    45
3533
0b8107a40da7 20183619 userland should support PGP signatures
Danek Duvall <danek.duvall@oracle.com>
parents: 1948
diff changeset
    46
* COMPONENT_SIG_URL is the URL where the PGP signature for $(COMPONENT_ARCHIVE)
0b8107a40da7 20183619 userland should support PGP signatures
Danek Duvall <danek.duvall@oracle.com>
parents: 1948
diff changeset
    47
  can be found.  This can be used in addition to the hash in
0b8107a40da7 20183619 userland should support PGP signatures
Danek Duvall <danek.duvall@oracle.com>
parents: 1948
diff changeset
    48
  $(COMPONENT_ARCHIVE_HASH) to verify the correctness of the archive.  If
0b8107a40da7 20183619 userland should support PGP signatures
Danek Duvall <danek.duvall@oracle.com>
parents: 1948
diff changeset
    49
  COMPONENT_SIG_URL is present, then COMPONENT_ARCHIVE_HASH needn't be, but its
0b8107a40da7 20183619 userland should support PGP signatures
Danek Duvall <danek.duvall@oracle.com>
parents: 1948
diff changeset
    50
  presence is strongly encouraged to ensure that the archive contents don't
4428
21fcfd647301 21131456 gpg2 missing from userland developer package
Danek Duvall <danek.duvall@oracle.com>
parents: 4196
diff changeset
    51
  change silently.  Note that when merging, because
3671
91f76aae1155 20381830 ctypes module unable to obtain default library path
John Beck <John.Beck@Oracle.COM>
parents: 3558
diff changeset
    52
  $WS/tools/.gnupg/pubring.gpg is a binary file, you will have to choose
91f76aae1155 20381830 ctypes module unable to obtain default library path
John Beck <John.Beck@Oracle.COM>
parents: 3558
diff changeset
    53
  the parent or child version.  Pick one, then run:
91f76aae1155 20381830 ctypes module unable to obtain default library path
John Beck <John.Beck@Oracle.COM>
parents: 3558
diff changeset
    54
	for cset in $(hg log -r 'parents()' -T '{node} '); do
91f76aae1155 20381830 ctypes module unable to obtain default library path
John Beck <John.Beck@Oracle.COM>
parents: 3558
diff changeset
    55
		hg cat -r $cset $WS/tools/.gnupg/pubring.gpg | \
91f76aae1155 20381830 ctypes module unable to obtain default library path
John Beck <John.Beck@Oracle.COM>
parents: 3558
diff changeset
    56
			gpg2 --homedir=$WS/tools/.gnupg --import;
91f76aae1155 20381830 ctypes module unable to obtain default library path
John Beck <John.Beck@Oracle.COM>
parents: 3558
diff changeset
    57
	done
91f76aae1155 20381830 ctypes module unable to obtain default library path
John Beck <John.Beck@Oracle.COM>
parents: 3558
diff changeset
    58
  before you 'hg commit' your merge.
5682
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    59
6911
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    60
* COMPONENT_LABEL is an arbitrary string that will be used as part of
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    61
  COMPONENT_SRC when building an archive from an SCM source repository.  It
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    62
  defaults to COMPONENT_VERSION.  It may be set to empty if desired.  See
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    63
  the relevant makefiles for the full composition.
7b878dfe6f0d 24661161 COMPONENT_SRC and COMPONENT_ARCHIVE are un-overridable in prep-*.mk
Danek Duvall <danek.duvall@oracle.com>
parents: 5682
diff changeset
    64
5682
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    65
* GIT_REPO can be used in place of COMPONENT_ARCHIVE_URL to pull the component
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    66
  source from the GIT repository referenced in the value.
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    67
* GIT_REV is the tag or changeset that you wish to pull from GIT.
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    68
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    69
* HG_REPO can be used in place of COMPONENT_ARCHIVE_URL to pull the component
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    70
  source from the Mercurial repository referenced in the value.
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    71
* HG_REV is the tag or changeset that you wish to pull from Mercurial.
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    72
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    73
* SVN_REPO can be used in place of COMPONENT_ARCHIVE_URL to pull the component
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    74
  source from the Subversion repository referenced in the value.
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    75
* SVN_REV is the tag or changeset that you wish to pull from Subversion.
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    76
3817
30b42c38bbc4 15786608 SUNBT7162754 create new meta package developer/opensolaris/userland
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 3701
diff changeset
    77
* REQUIRED_PACKAGES is a list of packages required to build or run the
5682
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    78
  component and its tests; it includes "system/library" by default.
1245
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    79
5682
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    80
The following are basic variables that must be set before including common.mk
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    81
if overriding the default:
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    82
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    83
* BUILD_STYLE declares what type of build process this component uses;
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    84
  possible values are: ant, archive (extract and copy), attpackagemake, cmake,
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    85
  configure, gnu-component, justmake, pkg (publish only), and setup.py.  See
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    86
  the corresponding file in make-rules for details.  The default value is
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    87
  'configure'.
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    88
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    89
  Based on the value of BUILD_STYLE, other variables are affected as follows:
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    90
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    91
  - If BUILD_STYLE is configure, CONFIGURE_ENV will automatically include
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    92
    CFLAGS, CXXFLAGS, and LDFLAGS.
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    93
  - If BUILD_STYLE is justmake, COMPONENT_BUILD_ENV will automatically include
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    94
    CC, CXX, CFLAGS, CXXFLAGS, and LDFLAGS.
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    95
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    96
* COMMON_TARGETS controls whether the standard build, configure, install,
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    97
  test, system-test targets are provided automatically.  Possible values
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    98
  are 'yes' and 'no'.  The default value is 'yes'.
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
    99
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   100
* BUILD_TARGET, INSTALL_TARGET, TEST_TARGET, SYSTEM_TEST_TARGET allow
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   101
  overriding the default targets provided by COMMON_TARGETS.  If set to a
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   102
  non-empty value, they act as an override.  If set to an empty value the
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   103
  target will not be defined by common.mk.  Instead of overriding the standard
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   104
  targets, it is suggested that the appropriate COMPONENT_PRE_*_ACTION or
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   105
  COMPONENT_POST_*_ACTION variables be used instead.
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   106
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   107
* BUILD_TARGET defaults to $(BUILD_$(BUILD_BITS))
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   108
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   109
* INSTALL_TARGET defaults to $(INSTALL_$(BUILD_BITS))
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   110
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   111
* TEST_TARGET defaults to $(TEST_$(BUILD_BITS))
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   112
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   113
* SYSTEM_TEST_TARGET default is determined by $(TEST_TARGET); if TEST_TARGET
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   114
  is not $(NO_TESTS) or $(SKIP_TEST), the default value is
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   115
  $(SYSTEM_TESTS_NOT_IMPLEMENTED)
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   116
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   117
The following variables alter the compilation or build process for components:
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   118
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   119
* ASLR_MODE controls the application of Address Space Layout Randomization to
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   120
  ELF binaries during the build.  The possible values are: $(ASLR_ENABLE),
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   121
  $(ASLR_DISABLE), $(ASLR_NOT_APPLICABLE).  If $(BUILD_BITS) is $(NO_ARCH),
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   122
  $(BUILD_STYLE) is 'ant', or $(COMPONENT_BUGDB) starts with 'library',
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   123
  $(ASLR_NOT_APPLICABLE) is the default.  Otherwise, the default is
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   124
  $(ASLR_ENABLE).
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   125
4196
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
   126
When using a source code management system as the canonical source for a
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
   127
component, the build automatically generates a source archive for the
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
   128
component by pulling the source from the SCM and creating a tarball from
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
   129
the pulled source.  This allows us to automatically store a copy of the
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
   130
canonical source that we build from in our source archive cache and not
7835
20c33a4fd225 25815962 components/Makefile should have pkglint target
John Beck <John.Beck@Oracle.COM>
parents: 7687
diff changeset
   131
continually hammer on the SCM repo for that component.  The source archive
20c33a4fd225 25815962 components/Makefile should have pkglint target
John Beck <John.Beck@Oracle.COM>
parents: 7687
diff changeset
   132
name is automatically generated from the COMPONENT_NAME, COMPONENT_VERSION,
4196
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
   133
and {GIT|HG|SVN}_REV values.  Also, the source is archived and unpacked
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
   134
in a directory using these values.   You should also define a hash for
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
   135
this tarball in your Makefile similar to what you do with downloaded
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
   136
source archives.
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
   137
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
   138
1245
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   139
These two are both initialized in make-rules/shared-macros.mk rather than any
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   140
component-level Makefile, but are frequently referenced from the latter.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   141
* COMPONENT_DIR is the top-level directory of the given component in question.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   142
* SOURCE_DIR is set to $(COMPONENT_DIR)/$(COMPONENT_SRC).
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   143
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   144
Additional pre/post configure, build, or install actions can be specified in
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   145
a component Makefile by setting them in one of the following macros.  None of
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   146
these have default values.  These are mostly used for miscellaneous set-up or
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   147
clean-up tweaks as their names suggest.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   148
* COMPONENT_PRE_CONFIGURE_ACTION is used by several components to clone a
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   149
  source directory.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   150
* COMPONENT_POST_CONFIGURE_ACTION
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   151
* COMPONENT_PRE_BUILD_ACTION
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   152
* COMPONENT_POST_BUILD_ACTION
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   153
* COMPONENT_PRE_INSTALL_ACTION
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   154
* COMPONENT_POST_INSTALL_ACTION
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   155
* COMPONENT_PRE_TEST_ACTION
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   156
* COMPONENT_POST_TEST_ACTION
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   157
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   158
If component specific make targets need to be used for build or install or
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   159
test, they can be specified via the following.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   160
* COMPONENT_BUILD_TARGETS is not usually set because the default target of most
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   161
  open source software is the equivalent of a 'build' target.  This needs to be
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   162
  set when building the software requires a different target than the default.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   163
  You should not override make macros here, but in COMPONENT_BUILD_ARGS.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   164
* COMPONENT_INSTALL_TARGETS has a default value of "install".  Very few
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   165
  components need to alter this.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   166
* COMPONENT_TEST_TARGETS has a default value of "check".  Several components
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   167
  need to set this to "test".
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   168
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   169
* COMPONENT_BUILD_ARGS is probably the mostly useful variable here for solving
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   170
  subtle build issues.  When you need to override a MACRO set in the native
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   171
  Makefile of a component, do so by adding something like:
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   172
     COMPONENT_BUILD_ARGS += MKDIR="$(MKDIR)"
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   173
  Quoting is often important because values with white-space can be split up,
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   174
  yielding the wrong results.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   175
* COMPONENT_BUILD_ENV is for when you just need to override things in the
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   176
  calling environment, like PATH.
5125
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   177
* COMPONENT_INSTALL_ARGS is mainly used for altering target directories;
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   178
  there are also COMPONENT_INSTALL_ARGS.$(BITS) versions.
1245
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   179
* COMPONENT_INSTALL_ENV is mainly used for altering target directories.
1907
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   180
* COMPONENT_PUBLISH_ENV is so far only used to work around Python issues when
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   181
  used by "pkgdepend generate", though the variable may be extended in the
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   182
  future for general "gmake publish" usage.
1245
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   183
* COMPONENT_TEST_ARGS is little used.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   184
* COMPONENT_TEST_ENV is mainly used for altering PATH and friends.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   185
3558
2cec274f17fc 20222479 Need a method to compare test results against a master in Userland
Rich Burridge <rich.burridge@oracle.com>
parents: 3533
diff changeset
   186
If your component needs to do some kind of cleanup after a "gmake test" run,
2cec274f17fc 20222479 Need a method to compare test results against a master in Userland
Rich Burridge <rich.burridge@oracle.com>
parents: 3533
diff changeset
   187
such as kill processes after doing a "gmake test" run, then this can be done
2cec274f17fc 20222479 Need a method to compare test results against a master in Userland
Rich Burridge <rich.burridge@oracle.com>
parents: 3533
diff changeset
   188
by setting COMPONENT_TEST_CLEANUP.
2cec274f17fc 20222479 Need a method to compare test results against a master in Userland
Rich Burridge <rich.burridge@oracle.com>
parents: 3533
diff changeset
   189
2cec274f17fc 20222479 Need a method to compare test results against a master in Userland
Rich Burridge <rich.burridge@oracle.com>
parents: 3533
diff changeset
   190
If you have created master test results file(s) for your component in the
2cec274f17fc 20222479 Need a method to compare test results against a master in Userland
Rich Burridge <rich.burridge@oracle.com>
parents: 3533
diff changeset
   191
COMPONENT_TEST_RESULTS_DIR directory, then in order to successfully compare
2cec274f17fc 20222479 Need a method to compare test results against a master in Userland
Rich Burridge <rich.burridge@oracle.com>
parents: 3533
diff changeset
   192
your test results against that master results file, you might need to
2cec274f17fc 20222479 Need a method to compare test results against a master in Userland
Rich Burridge <rich.burridge@oracle.com>
parents: 3533
diff changeset
   193
normalize some of the test output lines. This is done via a set of regular
2cec274f17fc 20222479 Need a method to compare test results against a master in Userland
Rich Burridge <rich.burridge@oracle.com>
parents: 3533
diff changeset
   194
expressions that are applied to the test results. There are some global
2cec274f17fc 20222479 Need a method to compare test results against a master in Userland
Rich Burridge <rich.burridge@oracle.com>
parents: 3533
diff changeset
   195
default ones in the COMPONENT_TEST_TRANSFORMS definition in shared-macros.mk,
2cec274f17fc 20222479 Need a method to compare test results against a master in Userland
Rich Burridge <rich.burridge@oracle.com>
parents: 3533
diff changeset
   196
but your component Makefile might have to += some more for specific transforms
2cec274f17fc 20222479 Need a method to compare test results against a master in Userland
Rich Burridge <rich.burridge@oracle.com>
parents: 3533
diff changeset
   197
that need to be applied to the test output for just this component.
2cec274f17fc 20222479 Need a method to compare test results against a master in Userland
Rich Burridge <rich.burridge@oracle.com>
parents: 3533
diff changeset
   198
3701
2c4a1656e035 20191770 allow exclusion of components for "gmake test" at the top level
April Chin <april.chin@oracle.com>
parents: 3671
diff changeset
   199
* SKIP_TEST_AT_TOP_LEVEL inclusion of this variable in a component Makefile
2c4a1656e035 20191770 allow exclusion of components for "gmake test" at the top level
April Chin <april.chin@oracle.com>
parents: 3671
diff changeset
   200
  will cause that component's tests to be skipped when running "gmake test"
5682
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   201
  at the top level.  It's often used for excluding long-running tests
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   202
  that may slow down comprehensive component testing.
3701
2c4a1656e035 20191770 allow exclusion of components for "gmake test" at the top level
April Chin <april.chin@oracle.com>
parents: 3671
diff changeset
   203
1245
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   204
* COMPONENT_POST_UNPACK_ACTION is for making minor alterations to the unpacked
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   205
  source directory before any patching has taken place.  It should almost never
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   206
  be used.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   207
* COMPONENT_PREP_ACTION is used to make alterations to the unpacked and patched
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   208
  source.  It should be used with care.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   209
5125
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   210
For components that have a configure target, the following macros are used to
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   211
control the options and arguments passed:
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   212
5682
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   213
* If BUILD_BITS is set before shared-macros.mk is included, the default directories
5125
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   214
  used for various configure options as documented below will change.  For
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   215
  example:
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   216
5682
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   217
  if BUILD_BITS=64 or BUILD_BITS= 64_and_32 explicitly:
5125
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   218
  	32-bit binaries -> $(CONFIGURE_PREFIX)/bin/$(MACH32)
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   219
	32-bit libraries -> $(CONFIGURE_PREFIX)/lib
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   220
  	64-bit binaries -> $(CONFIGURE_PREFIX)/bin
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   221
	64-bit libraries -> $(CONFIGURE_PREFIX)/lib/$(MACH64)
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   222
5682
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   223
  if BUILD_BITS=32 or BUILD_BITS=32_and_64 explicitly or BITS is unspecified:
5125
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   224
  	32-bit binaries -> $(CONFIGURE_PREFIX)/bin
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   225
	32-bit libraries -> $(CONFIGURE_PREFIX)/lib
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   226
  	64-bit binaries -> $(CONFIGURE_PREFIX)/bin/$(MACH64)
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   227
	64-bit libraries -> $(CONFIGURE_PREFIX)/lib/$(MACH64)
5682
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   228
* CC_FOR_BUILD and CXX_FOR_BUILD is included in CONFIGURE_ENV by default to
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   229
  ensure that 32-bit and 64-bit host detection works as expected for
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   230
  autoconf-based components by specifying the exact compiler and relevant
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   231
  $(CC_BITS) for the current build.  It can be set to "" to omit it from
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   232
  CONFIGURE_ENV.
5125
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   233
* CONFIGURE_CPPFLAGS contains the default set of CPPFLAGS to be included in
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   234
  CONFIGURE_ENV.  It can be set to "" to omit it from CONFIGURE_ENV.
1245
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   235
* CONFIGURE_DEFAULT_DIRS should be "yes" or "no".  A value of "yes" (the
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   236
  default) will trigger the following being passed to CONFIGURE_OPTIONS as
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   237
  parameters to corresponding options.
5125
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   238
  * CONFIGURE_BINDIR.$(BITS) is the value for the --bindir= option.
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   239
  * CONFIGURE_LIBDIR.$(BITS) is the value for the --libdir= option.
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   240
  * CONFIGURE_MANDIR.$(BITS) is the value for the --mandir= option.
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   241
  * CONFIGURE_SBINDIR.$(BITS) is the value for the --sbindir= option.
5682
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   242
* CONFIGURE_ENV is mainly used for passing Makefile variables to configure.
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   243
  When should this be used as opposed to CONFIGURE_OPTIONS and
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   244
  COMPONENT_BUILD_{ARGS,ENV}?  In general, you want to tell configure how to
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   245
  build the software using CONFIGURE_OPTIONS.  But sometimes you need to pass
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   246
  values in via the calling environment.  On rare occasions, you still need to
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   247
  do things like override MACRO settings in the generated Makefiles with
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   248
  COMPONENT_BUILD_ARGS.
1245
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   249
* CONFIGURE_LOCALEDIR is a cousin of the other *DIR variables above, but
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   250
  rarely used and hence not triggered by CONFIGURE_DEFAULT_DIRS.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   251
* CONFIGURE_OPTIONS is extremely useful, possibly our most used "add-on"
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   252
  variable, for passing various options to configure.  These tend to vary per
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   253
  component, but --enable-foo and --disable-foo for various values of foo are
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   254
  quite common.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   255
* CONFIGURE_PREFIX is the prefix for the various *DIR variables above.  Its
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   256
  default is "/usr"; set it if some other value (e.g., "/usr/gnu") is needed.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   257
* CONFIGURE_SCRIPT should be set if the default "$(SOURCE_DIR)/configure" is
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   258
  unsuitable for whatever reason.
1258
43768f8c79d5 16624973 document studio_OPT in doc/makefile-variables.txt
John Beck <John.Beck@Oracle.COM>
parents: 1245
diff changeset
   259
5125
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   260
To override or otherwise modify the default compilation flags used for
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   261
components, the following macros are provided:
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   262
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   263
* CFLAGS by default contains the preferred set of compilation flags for most
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   264
  components, which usually includes optimization flags, language mode,
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   265
  alignment flags, and multi-threading flags for the current COMPILER.
5682
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   266
  CFLAGS.$(COMPILER), CFLAGS.$(COMPILERS).$(BITS),
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   267
  CFLAGS.$(COMPILERS).$(MACH), and CFLAGS.$(COMPILERS).$(MACH).$(BITS)
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   268
  versions are also available for specifying additional flags or overriding
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   269
  the default.
5125
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   270
* CXXFLAGS by default contains the preferred set of compilation flags for most
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   271
  C++ components, which usually includes optimization flags, language mode,
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   272
  alignment flags, and multi-threading flags for the current COMPILER.
5682
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   273
  CXXFLAGS.$(COMPILER), CXXFLAGS.$(COMPILERS).$(BITS),
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   274
  CXXFLAGS.$(COMPILERS).$(MACH), and CXXFLAGS.$(COMPILERS).$(MACH).$(BITS)
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   275
  versions are also available for specifying additional flags or overriding
94c0ca64c022 15558602 TCL_LD_SEARCH_FLAGS is wrongly defined in tclConfig.sh
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5438
diff changeset
   276
  the default.
5125
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   277
* gcc_OPT has a default value of "-O3".  Bugs in the optimizer have been found
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   278
  which have required altering this to "-O2".
1258
43768f8c79d5 16624973 document studio_OPT in doc/makefile-variables.txt
John Beck <John.Beck@Oracle.COM>
parents: 1245
diff changeset
   279
* studio_OPT has a default value of "-xO4".  Occasional bugs in the optimizer
5125
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   280
  have been found which have required altering this to "-xO3".
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   281
* There are also gcc_OPT.$(MACH).$(BITS) and studio_OPT.$(MACH).$(BITS)
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   282
  versions of the above available if greater specificity is needed.
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   283
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   284
For components that use pkg-config, the following macros are provided:
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   285
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   286
* PKG_CONFIG_PATH contains the default system paths to use when looking for
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   287
  pkg-config configuration files.  To specify additional paths to be searched,
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   288
  use PKG_CONFIG_PATHS as follows:
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   289
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   290
  PKG_CONFIG_PATHS += /path/to/pc/files
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   291
34cc580c62c2 21029732 PKG_CONFIG_PATH should be included in CONFIGURE_ENV and BUILD_ENV
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 4428
diff changeset
   292
Finally, for control of packaging-related operations and values used during
5427
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   293
publication, the following variables are available:
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   294
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   295
* All variables named after the pattern COMPONENT_%(COMPONENT_NAME_%), such
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   296
  as COMPONENT_ARCHIVE_URL, COMPONENT_ARCHIVE_URL_1, etc.  Refer to ips.mk
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   297
  PKG_MACROS and PKG_VARS for a complete list.
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   298
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   299
* DQ, SQ, Q: a set of convenience macros that expand to ", ', and "
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   300
  respectively; $(Q) (or $Q) is simply the default quote with a short name
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   301
  for convenience.  For use with values in package manifests where the
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   302
  substituted value may contain whitespace.  For example:
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   303
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   304
  set name=pkg.human-version value=$(DQ)$(HUMAN_VERSION)$(DQ)
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   305
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   306
* PKG_MACROS: the list of makefile macros that should be exported as defines
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   307
  for use in package manifests and pkgmogrify transform files.  Whitespace is
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   308
  NOT supported; use of PKG_VARS is strongly preferred for this reason.  The
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   309
  expected form each of entry is a key-value pair as follows:
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   310
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   311
     PKG_MACROS += NAME=NO-WHITESPACE-VALUE
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   312
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   313
* PKG_VARS: the list of variables that should be exported as defines for use in
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   314
  package manifests and pkgmogrify transform files.  This list should generally
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   315
  only be added to, not redefined, as follows:
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   316
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   317
     PKG_VARS += VARIABLE_NAME
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   318
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   319
  Variable values may contain whitespace, although the value must be quoted
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   320
  appropriately in the package manifest if they do.  Variables must be assigned
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   321
  before the inclusion of ips.mk.  Values containing whitespace should not be
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   322
  quoted when declared in the Makefile; they should only be quoted using the
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   323
  appropriate macros in the package manifest.  Values cannot currently contain
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   324
  any characters that require shell escaping such as ", ', or *.
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   325
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   326
* PYVER is defined when processing package manifest files whose name end in
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   327
  -PYVER.p5m.  The package manifest will be processed for each version found in
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   328
  PYTHON_VERSIONS.  MAYBE_PYVER_SPACE (e.g. '2.7 ') and MAYBE_SPACE_PYVER
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   329
  (e.g. ' 2.7') are derived from PYVER if defined.  If PYVER is not defined
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   330
  (such as when a generic unversioned Python package manifest is being
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   331
  created), these are defined as ''.  perl and ruby follow the same pattern
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   332
  and define PERLVER, PERL_VERSIONS, MAYBE_SPACE_PERLVER, MAYBE_PERLVER_SPACE
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   333
  and RUBY_VERSION, RUBY_VERSIONS, MAYBE_RUBY_VERSION_SPACE,
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   334
  MAYBE_SPACE_RUBY_VERSION respectively.
1907
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   335
1948
2d1537e7942d 18978320 Userland components should specify TPNOs in Makefiles instead of pkg manifests
John Beck <John.Beck@Oracle.COM>
parents: 1907
diff changeset
   336
* TPNO is the Third Party number (i.e., a numeric value): the License
2d1537e7942d 18978320 Userland components should specify TPNOs in Makefiles instead of pkg manifests
John Beck <John.Beck@Oracle.COM>
parents: 1907
diff changeset
   337
  Technology from the Product Lifecycle Suite tool.  This should be used
2d1537e7942d 18978320 Userland components should specify TPNOs in Makefiles instead of pkg manifests
John Beck <John.Beck@Oracle.COM>
parents: 1907
diff changeset
   338
  in the common case when there is just one TPNO for a component.  We
2d1537e7942d 18978320 Userland components should specify TPNOs in Makefiles instead of pkg manifests
John Beck <John.Beck@Oracle.COM>
parents: 1907
diff changeset
   339
  recommend that this be near the top of any Makefile, just below the
2d1537e7942d 18978320 Userland components should specify TPNOs in Makefiles instead of pkg manifests
John Beck <John.Beck@Oracle.COM>
parents: 1907
diff changeset
   340
  various COMPONENT_foo definitions.
5427
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   341
1948
2d1537e7942d 18978320 Userland components should specify TPNOs in Makefiles instead of pkg manifests
John Beck <John.Beck@Oracle.COM>
parents: 1907
diff changeset
   342
* TPNO_foo is for the rare case (~3% of components) when a component has
2d1537e7942d 18978320 Userland components should specify TPNOs in Makefiles instead of pkg manifests
John Beck <John.Beck@Oracle.COM>
parents: 1907
diff changeset
   343
  more than one TPNO.  Each one should have a separate short but descriptive
2d1537e7942d 18978320 Userland components should specify TPNOs in Makefiles instead of pkg manifests
John Beck <John.Beck@Oracle.COM>
parents: 1907
diff changeset
   344
  name substituted for "foo".  This likewise should be near the top of any
2d1537e7942d 18978320 Userland components should specify TPNOs in Makefiles instead of pkg manifests
John Beck <John.Beck@Oracle.COM>
parents: 1907
diff changeset
   345
  Makefile, just below the various COMPONENT_foo definitions, and it must
5427
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   346
  also be before the inclusion of ips.mk.  All variables named after the
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   347
  pattern TPNO_% are automatically available for use in package manifests
25b736152081 15814060 SUNBT7196216 userland build mangles PKG_MACROS containing whitespace
Shawn Walker-Salas <shawn.walker@oracle.com>
parents: 5125
diff changeset
   348
  and pkgmogrify transform files.
7835
20c33a4fd225 25815962 components/Makefile should have pkglint target
John Beck <John.Beck@Oracle.COM>
parents: 7687
diff changeset
   349
5438
c068f8c677e8 PSARC/2016/016 Rename/Refactor Puppet and Puppet Module Packages
Shawn Ferry <shawn.ferry@oracle.com>
parents: 5427
diff changeset
   350
* PKGREPO_REMOVE_BEFORE_PUBLISH allows automatic removal of previously
c068f8c677e8 PSARC/2016/016 Rename/Refactor Puppet and Puppet Module Packages
Shawn Ferry <shawn.ferry@oracle.com>
parents: 5427
diff changeset
   351
  published components from PKG_REPO (including obsolete and renamed
c068f8c677e8 PSARC/2016/016 Rename/Refactor Puppet and Puppet Module Packages
Shawn Ferry <shawn.ferry@oracle.com>
parents: 5427
diff changeset
   352
  versions). When set as PKGREPO_REMOVE_BEFORE_PUBLISH=yes removal
c068f8c677e8 PSARC/2016/016 Rename/Refactor Puppet and Puppet Module Packages
Shawn Ferry <shawn.ferry@oracle.com>
parents: 5427
diff changeset
   353
  occurs immediately prior to pkgsend. default: "no"
c068f8c677e8 PSARC/2016/016 Rename/Refactor Puppet and Puppet Module Packages
Shawn Ferry <shawn.ferry@oracle.com>
parents: 5427
diff changeset
   354
7835
20c33a4fd225 25815962 components/Makefile should have pkglint target
John Beck <John.Beck@Oracle.COM>
parents: 7687
diff changeset
   355
* PKGLINT points to the pkglint(1) executable.  PKGLINTVAR points to either
20c33a4fd225 25815962 components/Makefile should have pkglint target
John Beck <John.Beck@Oracle.COM>
parents: 7687
diff changeset
   356
  PKGLINT or /bin/true depending on the invocation: for individual component
20c33a4fd225 25815962 components/Makefile should have pkglint target
John Beck <John.Beck@Oracle.COM>
parents: 7687
diff changeset
   357
  builds, we run pkglint at the end of the publish phase.  But for top-down
20c33a4fd225 25815962 components/Makefile should have pkglint target
John Beck <John.Beck@Oracle.COM>
parents: 7687
diff changeset
   358
  builds, running pkglint for each component would cause locking issues, so
20c33a4fd225 25815962 components/Makefile should have pkglint target
John Beck <John.Beck@Oracle.COM>
parents: 7687
diff changeset
   359
  we skip that step and run pkglint once at the end.  There is also a pkglint:
20c33a4fd225 25815962 components/Makefile should have pkglint target
John Beck <John.Beck@Oracle.COM>
parents: 7687
diff changeset
   360
  target in components/Makefile that allows for the direction invocation of
20c33a4fd225 25815962 components/Makefile should have pkglint target
John Beck <John.Beck@Oracle.COM>
parents: 7687
diff changeset
   361
  this end-of-the-build-pkglint-everything-together step, which makes it much
20c33a4fd225 25815962 components/Makefile should have pkglint target
John Beck <John.Beck@Oracle.COM>
parents: 7687
diff changeset
   362
  easier to "finish off" a build where a small number of components failed.
1948
2d1537e7942d 18978320 Userland components should specify TPNOs in Makefiles instead of pkg manifests
John Beck <John.Beck@Oracle.COM>
parents: 1907
diff changeset
   363
1907
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   364
---
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   365
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   366
Now switching from explaining the function of specific variables to a more
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   367
general discussion about how to use them to solve problems.  One method that
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   368
has served time and again is adding a level of indirection.  For example,
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   369
when Python 3 came along, we decided to build it 64-bit only, which meant
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   370
its various modules also needed to be built 64-bit only.  But many of them
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   371
had BUILD_32_and_64 in their native Makefile.  So how to tweak that macro
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   372
to do one thing for Python 2.x but another for 3.x?  JBeck spent an entire
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   373
day trying various combinations that seemed right, but none of them worked.
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   374
Then Norm pointed out that changing PYTHON_VERSIONS from "3.4 2.7 2.6" to
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   375
$(PYTHON3_VERSIONS) and $(PYTHON2_VERSIONS) which in turn were "3.4" and
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   376
"2.7 2.6" would do the trick.  I.e., adding a level of indirection solved
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   377
the problem, as it allowed $(PYTHON_VERSIONS) to be used to specify 64-bit
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   378
macros but $(PYTHON2_VERSIONS) to specify 32-bit macros.  There are many
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   379
other places where constructs like this are used.