solenv/gbuild/ExternalExecutable.mk

   1 # -*- Mode: makefile-gmake; tab-width: 4; indent-tabs-mode: t -*-
   2 #
   3 # This file is part of the LibreOffice project.
   4 #
   5 # This Source Code Form is subject to the terms of the Mozilla Public
   6 # License, v. 2.0. If a copy of the MPL was not distributed with this
   7 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8 #
   9
  10 # class ExternalExecutable
  11
  12 # ExternalExecutable is a little helper for using executables that might
  13 # either come from system or be built internally.
  14 #
  15 # === Setup ===
  16 #
  17 # An ExternalExecutable command consists of 4 parts:
  18 # * precommand: any command line variables that need to be set
  19 # * internal: unspecified command(s), possibly including calls of gdb,
  20 #   valgrind or icerun
  21 # * executable: the executable, with or without path
  22 # * arguments: command line arguments that are specific for either
  23 #   external or internal call, or that are common for _all_ uses of the
  24 #   executable
  25 #
  26 # The configuration is done in RepositoryExternal.mk by defining function
  27 # gb_ExternalExecutable__register_EXECUTABLE, which can call up to 4
  28 # functions:
  29 # * gb_ExternalExecutable_set_external / gb_ExternalExecutable_set_internal
  30 # * gb_ExternalExecutable_set_precommand
  31 # * gb_ExternalExecutable_add_dependencies
  32 # * gb_ExternalExecutable_add_arguments.
  33 # If neither gb_ExternalExecutable_set_external nor
  34 # gb_ExternalExecutable_set_internal is used, the executable defaults to
  35 # the ExternalExecutable's name. Due to that, nothing needs to be set
  36 # for an external executable in the typical case.
  37 #
  38 # All external executables must be registered (by listing the executable
  39 # name in gb_ExternalExecutable_register_executables call). This is done in
  40 # Repository.mk .
  41 #
  42 # === Usage ===
  43 #
  44 # The call site(s) should always use both of the following functions:
  45 # * gb_ExternalExecutable_get_command: the complete command for the
  46 #   executable
  47 # * gb_ExternalExecutable_get_dependencies: all run-time dependencies
  48 #   needed by the command.
  49
  50 ## Infrastructure functions
  51
  52 # The list of registered executables.
  53 gb_ExternalExecutable_REGISTERED_EXECUTABLES :=
  54
  55 define gb_ExternalExecutable__add_executable
  56 $(if $(filter $(executable),$(gb_ExternalExecutable_REGISTERED_EXECUTABLES)),\
  57     $(call gb_Output_error,external executable $(executable) has already been registered) \
  58 )
  59 gb_ExternalExecutable_REGISTERED_EXECUTABLES += $(1)
  60
  61 endef
  62
  63 # Register one or more external executables.
  64 #
  65 # gb_ExternalExecutable_register_executables executable(s)
  66 define gb_ExternalExecutable_register_executables
  67 $(foreach executable,$(1),$(call gb_ExternalExecutable__add_executable,$(executable)))
  68
  69 endef
  70
  71 define gb_ExternalExecutable__process_registration
  72 $(if $(filter undefined,$(origin gb_ExternalExecutable__register_$(executable))),\
  73     $(call gb_Output_error,there is no definition for external executable $(executable)) \
  74 )
  75 $(call gb_ExternalExecutable__register_$(executable))
  76
  77 endef
  78
  79 # Collect definitions for registered executables.
  80 #
  81 # The registration functions will be run.
  82 #
  83 # gb_ExternalExecutable_collect_registrations
  84 define gb_ExternalExecutable_collect_registrations
  85 $(eval $(foreach executable,$(gb_ExternalExecutable_REGISTERED_EXECUTABLES),\
  86         $(call gb_ExternalExecutable__process_registration,$(executable)))
  87 )
  88
  89 endef
  90
  91 define gb_ExternalExecutale__check_registration
  92 $(if $(filter $(1),$(gb_ExternalExecutable_REGISTERED_EXECUTABLES)),,\
  93         $(call gb_Output_error,external executable $(1) has not been registered) \
  94 )
  95
  96 endef
  97
  98 ## Setup functions
  99
 100 # Set the executable as external
 101 #
 102 # Optionally set a specific executable call to use.
 103 # Example:
 104 #       $(call gb_ExternalExecutable_set_external,genbrk,$(SYSTEM_GENBRK))
 105 #
 106 # gb_ExternalExecutable_set_external executable call?
 107 define gb_ExternalExecutable_set_external
 108 $(if $(2),gb_ExternalExecutable_$(1)_EXECUTABLE := $(2))
 109
 110 endef
 111
 112 # FIXME need to subst in some more $$ in gb_Helper_set_ld_path here - ugly
 113 # but other uses (gb_CppunitTest_CPPTESTPRECOMMAND) require less $$ - ugly
 114 define gb_ExternalExecutable__set_internal
 115 $(if $(3),,$(if $(filter $(WORKDIR_FOR_BUILD)/UnpackedTarball,$(2)),\
 116         $(call gb_Output_error,depending directly on executable $(2) from UnpackedTarball is not allowed. Use the UnpackedTarball target as dependency.)))
 117 gb_ExternalExecutable_$(1)_EXECUTABLE := $(2)
 118 gb_ExternalExecutable_$(1)_DEPENDENCIES := $(if $(3),$(call gb_Executable_get_target_for_build,$(3)),$(2))
 119 gb_ExternalExecutable_$(1)_PRECOMMAND := $(subst $$,$$$$,$(gb_Helper_set_ld_path)) $(BUILDTOOLTRACE)
 120
 121 endef
 122
 123 # Set the executable as internal
 124 #
 125 # Optionally set a specific executable target to use (if the target
 126 # $(gb_Executable_BINDIR_FOR_BUILD)/$(1)$(gb_Executable_EXT_for_build) is
 127 # not suitable). Also optionally, set the ExternalProject that builds
 128 # the executable. This is needed to create proper dependency for
 129 # executables that are not bundled # with libreoffice, so they are used
 130 # directly from workdir/UnpackedTarball/*.
 131 #
 132 # gb_ExternalExecutable_set_internal executable call? external?
 133 define gb_ExternalExecutable_set_internal
 134 $(call gb_ExternalExecutable__set_internal,$(1),$(if $(strip $(2)),$(2),$(gb_Executable_BINDIR_FOR_BUILD)/$(1)$(gb_Executable_EXT_for_build)),$(strip $(3)))
 135
 136 endef
 137
 138 # Set pre-command for the executable
 139 #
 140 # This call should set any command line variables needed for the
 141 # executable to run.
 142 #
 143 # gb_ExternalExecutable_set_precommand executable precommand
 144 define gb_ExternalExecutable_set_precommand
 145 gb_ExternalExecutable_$(1)_PRECOMMAND := $(2) $(BUILDTOOLTRACE)
 146
 147 endef
 148
 149 # Add dependencies needed for running the executable
 150 #
 151 # Note that the dependencies should in most (if not all) cases be
 152 # _for_build targets, or there might be problems in cross-compilation
 153 # Specifically, not using _for_build target would mean either:
 154 # * the target is built before the command even if it is not necessary
 155 #   (not really a problem, but might be a nuisance)
 156 # * the build breaks because the target is not known. This might happen
 157 #   if there is a difference in configuration between build and host
 158 #   phases.
 159 #
 160 # gb_ExternalExecutable_add_dependencies executable dependencies
 161 define gb_ExternalExecutable_add_dependencies
 162 gb_ExternalExecutable_$(1)_DEPENDENCIES += $(2)
 163
 164 endef
 165
 166 # Add arguments needed for running the executable
 167 #
 168 # This should only contain arguments that differ between external and
 169 # internal executable call or that are common for all call sites.
 170 #
 171 # gb_ExternalExecutable_add_arguments executable arguments
 172 define gb_ExternalExecutable_add_arguments
 173 gb_ExternalExecutable_$(1)_ARGUMENTS += $(2)
 174
 175 endef
 176
 177 ## User functions
 178
 179 gb_ExternalExecutable__get_internal := $(ICECREAM_RUN)
 180
 181 define gb_ExternalExecutable__get_executable
 182 $(if $(gb_ExternalExecutable_$(1)_EXECUTABLE),$(gb_ExternalExecutable_$(1)_EXECUTABLE),$(1))
 183 endef
 184
 185 define gb_ExternalExecutable__get_command
 186 $(call gb_ExternalExecutale__check_registration,$(1))
 187 $(gb_ExternalExecutable_$(1)_PRECOMMAND) \
 188         $(2) \
 189         $(call gb_ExternalExecutable__get_internal,$(1)) \
 190         $(call gb_ExternalExecutable__get_executable,$(1)) \
 191         $(gb_ExternalExecutable_$(1)_ARGUMENTS)
 192 endef
 193
 194 # Return the command for running an external executable.
 195 #
 196 # The command includes the required shell variables, if any (e.g.,
 197 # LD_LIBRARY_PATH for internally built executables), and icerun wrapper
 198 # for limiting the maximum number of processes, if available.
 199 #
 200 # $2 is an optional part (like "xargs") to place between the setting of shell variables and the
 201 # command proper.
 202 #
 203 # gb_ExternalExecutable_get_command executable
 204 define gb_ExternalExecutable_get_command
 205 $(strip $(call gb_ExternalExecutable__get_command,$(1),$(2)))
 206 endef
 207
 208 define gb_ExternalExecutable__get_dependencies
 209 $(call gb_ExternalExecutale__check_registration,$(1))
 210 $(gb_ExternalExecutable_$(1)_DEPENDENCIES)
 211 endef
 212
 213 # Return the dependencies needed for running an external executable.
 214 #
 215 # gb_ExternalExecutable_get_dependencies executable
 216 define gb_ExternalExecutable_get_dependencies
 217 $(strip $(call gb_ExternalExecutable__get_dependencies,$(1)))
 218 endef
 219
 220 # vim: set noet sw=4 ts=4: