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 define gb_ExternalExecutable__set_internal
 113 gb_ExternalExecutable_$(1)_EXECUTABLE := $(2)
 114 gb_ExternalExecutable_$(1)_DEPENDENCIES := $(2)
 115 gb_ExternalExecutable_$(1)_PRECOMMAND := $(gb_Helper_set_ld_path)
 116
 117 endef
 118
 119 # Set the executable as internal
 120 #
 121 # Optionally set a specific executable target to use (if the target
 122 # returned by gb_Executable_get_target_for_build is not suitable).
 123 #
 124 # gb_ExternalExecutable_set_internal executable call?
 125 define gb_ExternalExecutable_set_internal
 126 $(call gb_ExternalExecutable__set_internal,$(1),$(if $(strip $(2)),$(2),$(call gb_Executable_get_target_for_build,$(1))))
 127
 128 endef
 129
 130 # Set pre-command for the executable
 131 #
 132 # This call should set any command line variables needed for the
 133 # executable to run.
 134 #
 135 # gb_ExternalExecutable_set_precommand executable precommand
 136 define gb_ExternalExecutable_set_precommand
 137 gb_ExternalExecutable_$(1)_PRECOMMAND := $(2)
 138
 139 endef
 140
 141 # Add dependencies needed for running the executable
 142 #
 143 # Note that the dependencies should in most (if not all) cases be
 144 # _for_build targets, or there might be problems in cross-compilation
 145 # Specifically, not using _for_build target would mean either:
 146 # * the target is built before the command even if it is not necessary
 147 #   (not really a problem, but might be a nuisance)
 148 # * the build breaks because the target is not known. This might happen
 149 #   if there is a difference in configuration between build and host
 150 #   phases.
 151 #
 152 # gb_ExternalExecutable_add_dependencies executable dependencies
 153 define gb_ExternalExecutable_add_dependencies
 154 gb_ExternalExecutable_$(1)_DEPENDENCIES += $(2)
 155
 156 endef
 157
 158 # Add arguments needed for running the executable
 159 #
 160 # This should only contain arguments that differ between external and
 161 # internal executable call or that are common for all call sites.
 162 #
 163 # gb_ExternalExecutable_add_arguments executable arguments
 164 define gb_ExternalExecutable_add_arguments
 165 gb_ExternalExecutable_$(1)_ARGUMENTS += $(2)
 166
 167 endef
 168
 169 ## User functions
 170
 171 gb_ExternalExecutable__get_internal := $(ICECREAM_RUN)
 172
 173 define gb_ExternalExecutable__get_executable
 174 $(if $(gb_ExternalExecutable_$(1)_EXECUTABLE),$(gb_ExternalExecutable_$(1)_EXECUTABLE),$(1))
 175 endef
 176
 177 define gb_ExternalExecutable__get_command
 178 $(call gb_ExternalExecutale__check_registration,$(1))
 179 $(gb_ExternalExecutable_$(1)_PRECOMMAND) \
 180         $(call gb_ExternalExecutable__get_internal,$(1)) \
 181         $(call gb_ExternalExecutable__get_executable,$(1)) \
 182         $(gb_ExternalExecutable_$(1)_ARGUMENTS)
 183 endef
 184
 185 # Return the command for running an external executable.
 186 #
 187 # The command includes the required shell variables, if any (e.g.,
 188 # LD_LIBRARY_PATH for internally built executables), and icerun wrapper
 189 # for limiting the maximum number of processes, if available.
 190 #
 191 # gb_ExternalExecutable_get_command executable
 192 define gb_ExternalExecutable_get_command
 193 $(strip $(call gb_ExternalExecutable__get_command,$(1)))
 194 endef
 195
 196 define gb_ExternalExecutable__get_dependencies
 197 $(call gb_ExternalExecutale__check_registration,$(1))
 198 $(gb_ExternalExecutable_$(1)_DEPENDENCIES)
 199 endef
 200
 201 # Return the dependencies needed for running an external executable.
 202 #
 203 # gb_ExternalExecutable_get_dependencies executable
 204 define gb_ExternalExecutable_get_dependencies
 205 $(strip $(call gb_ExternalExecutable__get_dependencies,$(1)))
 206 endef
 207
 208 # vim: set noet sw=4 ts=4: