thunderbird: update to 128.2.2
[oi-userland.git] / doc / makefile-targets.txt
blob4499f00f562de33662e163aa028af6d4a77879b4
1 This is a guide to explain various useful targets in Userland component
2 Makefiles.  There is a set of targets that all Makefiles must include, plus
3 some addtional targets that are there for convenience.
5 component-environment-check::
6   This target is present in all Makefiles.  It is defined in
7   $(WS_MAKE_RULES)/environment.mk which is included by
8   $(WS_MAKE_RULES)/shares-macros.mk.  It reports on some interesting
9   information about the current environment and whether or not it is suitable
10   to build and/or publish the component.
12 component-environment-prep::
13   This target is present in all Makefiles.  It is defined in
14   $(WS_MAKE_RULES)/environment.mk which is included by
15   $(WS_MAKE_RULES)/shares-macros.mk.  It uses both USERLAND_REQUIRED_PACKAGES
16   and REQUIRED_PACKAGES macro contents to attempt to install any required
17   packages in the current environment.  To use this target user has to be
18   assigned "Software Installation" or "Primary Administrator" profile.
20 component-test-environment-check::
21   This target is present in all Makefiles.  It is defined in
22   $(WS_MAKE_RULES)/environment.mk which is included by
23   $(WS_MAKE_RULES)/shares-macros.mk.  It reports on some interesting
24   information about the current environment and whether or not it is suitable
25   to test the component.
27 component-test-environment-prep::
28   This target is present in all Makefiles.  It is defined in
29   $(WS_MAKE_RULES)/environment.mk which is included by
30   $(WS_MAKE_RULES)/shares-macros.mk.  It uses both
31   USERLAND_TEST_REQUIRED_PACKAGES and TEST_REQUIRED_PACKAGES macro contents to
32   attempt to install any required packages in the current environment.  To use
33   this target user has to be assigned "Software Installation" or "Primary
34   Administrator" profile.
36 download::
37   This target is present in all Makefiles.  It can be used at the top level
38   to act across all components, or on an individual component basis.  It is
39   typically defined by including $(WS_MAKE_RULES)/common.mk in your component
40   Makefile.  This target depends on your component Makefile, so changes to your
41   component Makefile will automatically trigger a re-download and subsequent
42   build steps that depend on it.  You can use the MAKEFILE_PREREQ macro to
43   override this behaviour and avoid rebuilding with each Makefile change.  This
44   macro should only be used in the calling environment via something like:
45     $ gmake MAKEFILE_PREREQ= install
47 unpack::
48   This target is present in all Makefiles.  It can be used at the top level
49   to act across all components, or on an individual component basis.  It is
50   typically defined by including $(WS_MAKE_RULES)/common.mk in your component
51   Makefile.  This target depends on the previously described "download" target,
52   This target will unpack any downloaded source archives.  It is an interim
53   step in the source code preparation phase of the build.
55 patch::
56   This target is present in all Makefiles.  It can be used at the top level
57   to act across all components, or on an individual component basis.  It is
58   typically defined by including $(WS_MAKE_RULES)/common.mk in your component
59   Makefile.  This target depends on the previously described "unpack" target,
60   This target will patch any unpacked source.  It is an interim step in the
61   source code preparation phase of the build.
63 prep::
64   This target is present in all Makefiles.  It can be used at the top level
65   to act across all components, or on an individual component basis.  It is 
66   typically defined by including $(WS_MAKE_RULES)/common.mk in your component
67   Makefile.  It depends on the previously described "download" target, as well
68   as internal interim targets to unpack source archives and apply patches to
69   the unpacked source.
71 build::
72   This target must be present in all Makefiles.  It can be used at the top level
73   to act across all components, or on an individual component basis.  It is
74   defined in the individual component Makefiles, but most Makefile fragments
75   under $(WS_MAKE_RULES) include targets that allow the definitions to depend
76   on one of several convenience macros $(BUILD_32), $(BUILD_64),
77   $(BUILD_32_and_64), and $(BUILD_NO_ARCH) to build 32-bit support, 64-bit
78   support, both 32 and 64 bit support, or architecture neutral support.  The
79   macro used will depend on the component.
81 install::
82   This target must be present in all Makefiles.  It can be used at the top level
83   to act across all components, or on an individual component basis.  It is
84   defined in the individual component Makefiles, but most Makefile fragments
85   under $(WS_MAKE_RULES) include targets that allow the definitions to depend
86   on one of several convenience macros $(INSTALL_32), $(INSTALL_64),
87   $(INSTALL_32_and_64), and $(INSTALL_NO_ARCH) to install 32-bit support, 64-bit
88   support, both 32 and 64 bit support, or architecture neutral support.  The
89   macro used will depend on the component and corresponds to the build target
90   macro used.
92 pkglint::
93   This target is an optional target is automatically defined in each Makefile
94   by the inclusion of $(WS_MAKE_RULES)/common.mk.  It will run the build steps
95   necessary to pkglint the manifests for a component.
97 pre-publish::
98   This target is present in all Makefiles.  It can be used at the top level
99   to act across all components, or on an individual component basis.  It is
100   automatically defined by including $(WS_MAKE_RULES)/common.mk.  It depends
101   on the previously described 'install' target and will perform a series of
102   internal, intermediate steps to use the component package manifests to
103   generate and validate consistency of packages for that component.
105   NOTE: The pre-publish target aims to help a recipe developer to make sure
106   that the recipe can produce a valid package without actually pushing its
107   bits into his or her repository (allows to experiment, saves some time, and
108   avoids polluting the repository with known-bad code during development cycles).
110 publish::
111   This target is present in all Makefiles.  It can be used at the top level
112   to act across all components, or on an individual component basis.  It is
113   automatically defined by including $(WS_MAKE_RULES)/common.mk.  It depends
114   on the previously described 'pre-publish' target and will actually publish
115   packages for that component to the repository configured in $(WS_REPO).
117 clean::
118   This target is present in all Makefiles.  It can be used at the top level
119   to act across all components, or on an individual component basis.  It is
120   automatically defined by including $(WS_MAKE_RULES)/common.mk.  It cleans
121   up any files created by building the component with the exception of any
122   downloaded files.
124 clobber::
126   This target is present in all Makefiles.  It can be used at the top level
127   to act across all components, or on an individual component basis.  It is
128   automatically defined by including $(WS_MAKE_RULES)/common.mk.  It depends
129   on the previously described 'clean' target and additionally cleans up any
130   downloaded source archives.
132 REQUIRED_PACKAGES::
133   This target is present in all component Makefiles.  It is automatically
134   defined by including $(WS_MAKE_RULES)/common.mk.  It is a convenience that can
135   be used to generate the set of REQUIRED_PACKAGES that is needed by the
136   'pkgdepend resolve' portion of package generation and publication (publish
137   target).  It automatically appends to the component Makefile, but the results
138   should be manually verified.
140 env-check::
141   This target serves as an alias for component-environment-check target. It exists
142   only for user convenience.
144 env-prep::
145   This target serves as an alias for component-environment-prep target. It exists
146   only for user convenience.
148 test-env-check::
149   This target serves as an alias for component-test-environment-check target.
150   It exists only for user convenience.
152 test-env-prep::
153   This target serves as an alias for component-test-environment-prep target. It
154   exists only for user convenience.
156 print-VAR
157   This target will print contents of variable VAR and also provide information
158   about variable origin and variable flavor.
160 print-value-VAR
161   This target will print contents of variable VAR.
163 format
164   This target will apply different refactoring rules to update the Makefile
165   to the current style: deprecation of macros, use of new target, autoindent...
166   The rules are implemented in the userland-component utility.
168 update
169   This target will format the Makefile then bump the COMPONENT_REVISION variable
170   if no VERSION value is provided. If a VERSION value is provided it will set
171   the COMPONENT_VERSION to the given value and remove COMPONENT_REVISION.
172   For some supported build style it may peform additional actions like:
173   - infering the latest version if VERSION=latest is passed,
174   - updating the archive checksum.
176 update-latest
177   This target is a convenience shortcut for 'update VERSION=latest'.