doc/makefile-variables.txt
author saurabh.vyas@oracle.com
Fri, 08 May 2015 11:22:54 -0700
changeset 4264 7d52b0c22474
parent 4196 d697072a92f5
child 4428 21fcfd647301
permissions -rw-r--r--
21027466 problem in SERVICE/KEYSTONE
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
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
     5
The following are the basics that just about every Makefile should have.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
     6
* COMPONENT_NAME is typically a short name (e.g., vim).
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
     7
* COMPONENT_VERSION is typically numbers separated by dots (e.g. 7.3).
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
     8
* COMPONENT_SRC is where the archive is extracted.  A common value for this is
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
     9
  "$(COMPONENT_NAME)-$(COMPONENT_VERSION)".
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    10
* COMPONENT_PROJECT_URL is the general web site for the component.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    11
* COMPONENT_ARCHIVE is the base name of the archive to be downloaded.  A common
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    12
  value for this is "$(COMPONENT_SRC).tar.gz".
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    13
* 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
    14
  field of `sha256sum $(COMPONENT_ARCHIVE)`.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    15
* 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
    16
  typically constructed from $(COMPONENT_PROJECT_URL) and $(COMPONENT_ARCHIVE).
3533
0b8107a40da7 20183619 userland should support PGP signatures
Danek Duvall <danek.duvall@oracle.com>
parents: 1948
diff changeset
    17
* 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
    18
  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
    19
  $(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
    20
  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
    21
  presence is strongly encouraged to ensure that the archive contents don't
0b8107a40da7 20183619 userland should support PGP signatures
Danek Duvall <danek.duvall@oracle.com>
parents: 1948
diff changeset
    22
  change silently.  If the signature results in a new key being added to
0b8107a40da7 20183619 userland should support PGP signatures
Danek Duvall <danek.duvall@oracle.com>
parents: 1948
diff changeset
    23
  tools/.gnupg/pubring.pgp, then as part of your code review, please show the
0b8107a40da7 20183619 userland should support PGP signatures
Danek Duvall <danek.duvall@oracle.com>
parents: 1948
diff changeset
    24
  diffs of the text version of the file by running
0b8107a40da7 20183619 userland should support PGP signatures
Danek Duvall <danek.duvall@oracle.com>
parents: 1948
diff changeset
    25
      gpg2 --homedir $WS/tools/.gnupg --fingerprint
3671
91f76aae1155 20381830 ctypes module unable to obtain default library path
John Beck <John.Beck@Oracle.COM>
parents: 3558
diff changeset
    26
  both before and after the change.  Note that when merging, because
91f76aae1155 20381830 ctypes module unable to obtain default library path
John Beck <John.Beck@Oracle.COM>
parents: 3558
diff changeset
    27
  $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
    28
  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
    29
	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
    30
		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
    31
			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
    32
	done
91f76aae1155 20381830 ctypes module unable to obtain default library path
John Beck <John.Beck@Oracle.COM>
parents: 3558
diff changeset
    33
  before you 'hg commit' your merge.
1245
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    34
* COMPONENT_BUGDB is the lower-case rendering of the BugDB cat/subcat.
3817
30b42c38bbc4 15786608 SUNBT7162754 create new meta package developer/opensolaris/userland
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 3701
diff changeset
    35
* REQUIRED_PACKAGES is a list of packages required to build or run the
30b42c38bbc4 15786608 SUNBT7162754 create new meta package developer/opensolaris/userland
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 3701
diff changeset
    36
  component and its tests.
1245
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    37
4196
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
    38
* GIT_REPO can be used in place of COMPONENT_ARCHIVE_URL to pull the component
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
    39
  source from the GIT repository referenced in the value.
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
    40
* GIT_REV is the tag or changeset that you wish to pull from GIT.
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
    41
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
    42
* HG_REPO can be used in place of COMPONENT_ARCHIVE_URL to pull the component
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
    43
  source from the Mercurial repository referenced in the value.
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
    44
* HG_REV is the tag or changeset that you wish to pull from Mercurial.
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
    45
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
    46
* SVN_REPO can be used in place of COMPONENT_ARCHIVE_URL to pull the component
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
    47
  source from the Subversion repository referenced in the value.
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
    48
* SVN_REV is the tag or changeset that you wish to pull from Subversion.
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
    49
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
    50
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
    51
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
    52
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
    53
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
    54
canonical source that we build from in our source archive cache and not
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
    55
continually hammer on the component's SCM repo.  The source archive name
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
    56
is automatically generated from the COMPONENT_NAME, COMPONENT_VERSION,
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
    57
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
    58
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
    59
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
    60
source archives.
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
    61
d697072a92f5 19782029 userland should be able to build from SCM repositories
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 3817
diff changeset
    62
1245
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    63
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
    64
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
    65
* 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
    66
* 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
    67
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    68
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
    69
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
    70
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
    71
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
    72
* 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
    73
  source directory.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    74
* COMPONENT_POST_CONFIGURE_ACTION
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    75
* COMPONENT_PRE_BUILD_ACTION
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    76
* COMPONENT_POST_BUILD_ACTION
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    77
* COMPONENT_PRE_INSTALL_ACTION
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    78
* COMPONENT_POST_INSTALL_ACTION
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    79
* COMPONENT_PRE_TEST_ACTION
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    80
* COMPONENT_POST_TEST_ACTION
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    81
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    82
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
    83
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
    84
* 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
    85
  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
    86
  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
    87
  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
    88
* 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
    89
  components need to alter this.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    90
* 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
    91
  need to set this to "test".
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    92
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    93
* 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
    94
  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
    95
  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
    96
     COMPONENT_BUILD_ARGS += MKDIR="$(MKDIR)"
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    97
  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
    98
  yielding the wrong results.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    99
* 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
   100
  calling environment, like PATH.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   101
* COMPONENT_INSTALL_ARGS is mainly used for altering target directories.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   102
* 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
   103
* 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
   104
  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
   105
  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
   106
* COMPONENT_TEST_ARGS is little used.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   107
* 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
   108
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
   109
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
   110
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
   111
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
   112
2cec274f17fc 20222479 Need a method to compare test results against a master in Userland
Rich Burridge <rich.burridge@oracle.com>
parents: 3533
diff changeset
   113
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
   114
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
   115
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
   116
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
   117
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
   118
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
   119
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
   120
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
   121
3701
2c4a1656e035 20191770 allow exclusion of components for "gmake test" at the top level
April Chin <april.chin@oracle.com>
parents: 3671
diff changeset
   122
* 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
   123
  will cause that component's tests to be skipped when running "gmake test"
2c4a1656e035 20191770 allow exclusion of components for "gmake test" at the top level
April Chin <april.chin@oracle.com>
parents: 3671
diff changeset
   124
  at the top level.  It's often used for excluding long-running tests 
2c4a1656e035 20191770 allow exclusion of components for "gmake test" at the top level
April Chin <april.chin@oracle.com>
parents: 3671
diff changeset
   125
  that may slow down comprehensive component testing.  
2c4a1656e035 20191770 allow exclusion of components for "gmake test" at the top level
April Chin <april.chin@oracle.com>
parents: 3671
diff changeset
   126
1245
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   127
* 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
   128
  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
   129
  be used.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   130
* 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
   131
  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
   132
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   133
* 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
   134
  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
   135
  parameters to corresponding options.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   136
  * CONFIGURE_BINDIR is the value for the --bindir= option.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   137
  * CONFIGURE_LIBDIR is the value for the --libdir= option.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   138
  * CONFIGURE_MANDIR is the value for the --mandir= option.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   139
  * CONFIGURE_SBINDIR is the value for the --sbindir= option.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   140
* CONFIGURE_ENV is mainly used for passing CFLAGS and other common Makefile
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   141
  variables to configure.  When should this be used as opposed to
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   142
  CONFIGURE_OPTIONS and COMPONENT_BUILD_{ARGS,ENV}?  In general, you want
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   143
  to tell configure how to build the software using CONFIGURE_OPTIONS.  But
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   144
  sometimes you need to pass values in via the calling environment.  On rare
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   145
  occasions, you still need to do things like override MACRO settings in the
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   146
  generated Makefiles with COMPONENT_BUILD_ARGS.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   147
* 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
   148
  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
   149
* 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
   150
  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
   151
  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
   152
  quite common.
b95e96615c0c 16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
   153
* 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
   154
  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
   155
* 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
   156
  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
   157
43768f8c79d5 16624973 document studio_OPT in doc/makefile-variables.txt
John Beck <John.Beck@Oracle.COM>
parents: 1245
diff changeset
   158
* studio_OPT has a default value of "-xO4".  Occasional bugs in the optimizer
43768f8c79d5 16624973 document studio_OPT in doc/makefile-variables.txt
John Beck <John.Beck@Oracle.COM>
parents: 1245
diff changeset
   159
  have been found which have required altering this to "-xO3".  There are also
43768f8c79d5 16624973 document studio_OPT in doc/makefile-variables.txt
John Beck <John.Beck@Oracle.COM>
parents: 1245
diff changeset
   160
  studio_OPT.$(MACH).$(BITS) versions of this available if greater specificity
43768f8c79d5 16624973 document studio_OPT in doc/makefile-variables.txt
John Beck <John.Beck@Oracle.COM>
parents: 1245
diff changeset
   161
  is needed.
1907
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   162
1948
2d1537e7942d 18978320 Userland components should specify TPNOs in Makefiles instead of pkg manifests
John Beck <John.Beck@Oracle.COM>
parents: 1907
diff changeset
   163
* 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
   164
  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
   165
  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
   166
  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
   167
  various COMPONENT_foo definitions.
2d1537e7942d 18978320 Userland components should specify TPNOs in Makefiles instead of pkg manifests
John Beck <John.Beck@Oracle.COM>
parents: 1907
diff changeset
   168
* 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
   169
  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
   170
  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
   171
  Makefile, just below the various COMPONENT_foo definitions, and it must
2d1537e7942d 18978320 Userland components should specify TPNOs in Makefiles instead of pkg manifests
John Beck <John.Beck@Oracle.COM>
parents: 1907
diff changeset
   172
  also be before the inclusion of ips.mk .
2d1537e7942d 18978320 Userland components should specify TPNOs in Makefiles instead of pkg manifests
John Beck <John.Beck@Oracle.COM>
parents: 1907
diff changeset
   173
1907
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   174
---
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   175
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1258
diff changeset
   176
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
   177
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
   178
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
   179
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
   180
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
   181
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
   182
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
   183
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
   184
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
   185
$(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
   186
"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
   187
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
   188
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
   189
other places where constructs like this are used.