aboutsummaryrefslogtreecommitdiff
path: root/cmake/Modules/FindABIMap.cmake
blob: 9579f91e6025519f54293119176604516820e9cb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
#
#  Copyright (c) 2018 Anderson Toshiyuki Sasaki <ansasaki@redhat.com>
#
#  Redistribution and use is allowed according to the terms of the New
#  BSD license.
#  For details see the accompanying COPYING-CMAKE-SCRIPTS file.
#

#.rst:
# FindABIMap
# ----------
#
# This file provides functions to generate the symbol version script. It uses
# the ``abimap`` tool to generate and update the linker script file. It can be
# installed by calling::
#
#   $ pip install abimap
#
# The ``function generate_map_file`` generates a symbol version script
# containing the provided symbols. It defines a custom command which sets
# ``target_name`` as its ``OUTPUT``.
#
# The experimental function ``extract_symbols()`` is provided as a simple
# parser to extract the symbols from C header files. It simply extracts symbols
# followed by an opening '``(``'. It is recommended to use a filter pattern to
# select the lines to be considered. It defines a custom command which sets
# ``target_name`` as its output.
#
# The helper function ``get_files_list()`` is provided to find files given a
# name pattern. It defines a custom command which sets ``target_name`` as its
# output.
#
# Functions provided
# ------------------
#
# ::
#
#   generate_map_file(target_name
#                     RELEASE_NAME_VERSION release_name
#                     SYMBOLS symbols_target
#                     [CURRENT_MAP cur_map]
#                     [FINAL]
#                     [BREAK_ABI]
#                     [COPY_TO output]
#                    )
#
# ``target_name``:
#   Required, expects the name of the file to receive the generated symbol
#   version script. It should be added as a dependency for the library. Use the
#   linker option ``--version-script filename`` to add the version information
#   to the symbols when building the library.
#
# ``RELEASE_NAME_VERSION``:
#   Required, expects a string containing the name and version information to be
#   added to the symbols in the format ``lib_name_1_2_3``.
#
# ``SYMBOLS``:
#   Required, expects a target with the property ``LIST_FILE`` containing a path
#   to a file containing the list of symbols to be added to the symbol version
#   script.
#
# ``CURRENT_MAP``:
#   Optional. If given, the new set of symbols will be checked against the
#   ones contained in the ``cur_map`` file and updated properly. If an
#   incompatible change is detected and ``BREAK_ABI`` is not defined, the build
#   will fail.
#
# ``FINAL``:
#   Optional. If given, will provide the ``--final`` option to ``abimap`` tool,
#   which will mark the modified release in the symbol version script with a
#   special comment, preventing later changes. This option should be set when
#   creating a library release and the resulting map file should be stored with
#   the source code.
#
# ``BREAK_ABI``:
#   Optional. If provided, will use ``abimap`` ``--allow-abi-break`` option, which
#   accepts incompatible changes to the set of symbols. This is necessary if any
#   previously existing symbol were removed.
#
# ``COPY_TO``:
#   Optional, expects a string containing the path to where the generated
#   map file will be copied.
#
# Example:
#
# .. code-block:: cmake
#
#   find_package(ABIMap)
#   generate_map_file("lib.map"
#                     RELEASE_NAME_VERSION "lib_1_0_0"
#                     SYMBOLS symbols
#                    )
#
# Where the target ``symbols`` has its property ``LIST_FILE`` set to the path to
# a file containing::
#
#  ``symbol1``
#  ``symbol2``
#
# This example would result in the symbol version script to be created in
# ``${CMAKE_CURRENT_BINARY_DIR}/lib.map`` containing the provided symbols.
#
# ::
#
#   get_files_list(target_name
#                   DIRECTORIES dir1 [dir2 ...]
#                   FILES_PATTERNS exp1 [exp2 ...]
#                   [COPY_TO output]
#                  )
#
# ``target_name``:
#   Required, expects the name of the target to be created. A file named as
#   ``${target_name}.list`` will be created in
#   ``${CMAKE_CURRENT_BINARY_DIR}`` to receive the list of files found.
#
# ``DIRECTORIES``:
#   Required, expects a list of directories paths. Only absolute paths are
#   supported.
#
# ``FILES_PATTERN``:
#   Required, expects a list of matching expressions to find the files to be
#   considered in the directories.
#
# ``COPY_TO``:
#   Optional, expects a string containing the path to where the file containing
#   the list of files will be copied.
#
# This command searches the directories provided in ``DIRECTORIES`` for files
# matching any of the patterns provided in ``FILES_PATTERNS``. The obtained list
# is written to the path specified by ``output``. A target named ``target_name``
# will be created and its property ``LIST_FILE`` will be set to contain
# ``${CMAKE_CURRENT_BINARY_DIR}/${target_name}.list``
#
# Example:
#
# .. code-block:: cmake
#
#   find_package(ABIMap)
#   get_files_list(target
#     DIRECTORIES "/include/mylib"
#     FILES_PATTERNS "*.h"
#     COPY_TO "my_list.txt"
#   )
#
# Consider that ``/include/mylib`` contains 3 files, ``h1.h``, ``h2.h``, and
# ``h3.hpp``
#
# Will result in a file ``my_list.txt`` containing::
#
#   ``h1.h;h2.h``
#
# And the target ``target`` will have its property ``LIST_FILE`` set to contain
# ``${CMAKE_CURRENT_BINARY_DIR}/target.list``
#
# ::
#
#   extract_symbols(target_name
#                   HEADERS_LIST headers_list_target
#                   [FILTER_PATTERN pattern]
#                   [COPY_TO output]
#                  )
#
# ``target_name``:
#   Required, expects the name of the target to be created. A file named after
#   the string given in ``target_name`` will be created in
#   ``${CMAKE_CURRENT_BINARY_DIR}`` to receive the list of symbols.
#
# ``HEADERS_LIST``:
#   Required, expects a target with the property ``LIST_FILE`` set, containing a
#   file path. Such file must contain a list of files paths.
#
# ``FILTER_PATTERN``:
#   Optional, expects a string. Only the lines containing the filter pattern
#   will be considered.
#
# ``COPY_TO``:
#   Optional, expects a string containing the path to where the file containing
#   the found symbols will be copied.
#
# This command extracts the symbols from the files listed in
# ``headers_list`` and write them on the ``output`` file. If ``pattern``
# is provided, then only the lines containing the string given in ``pattern``
# will be considered. It is recommended to provide a ``FILTER_PATTERN`` to mark
# the lines containing exported function declaration, since this function is
# experimental and can return wrong symbols when parsing the header files. A
# target named ``target_name`` will be created with the property ``LIST_FILE``
# set to contain ``${CMAKE_CURRENT_BINARY_DIR}/${target_name}.list``.
#
# Example:
#
# .. code-block:: cmake
#
#   find_package(ABIMap)
#   extract_symbols("lib.symbols"
#     HEADERS_LIST "headers_target"
#     FILTER_PATTERN "API_FUNCTION"
#   )
#
# Where ``LIST_FILE`` property in ``headers_target`` points to a file
# containing::
#
#   header1.h;header2.h
#
# Where ``header1.h`` contains::
#
#   API_FUNCTION int exported_func1(int a, int b);
#
# ``header2.h`` contains::
#
#   API_FUNCTION int exported_func2(int a);
#
#   int private_func2(int b);
#
# Will result in a file ``lib.symbols.list`` in ``${CMAKE_CURRENT_BINARY_DIR}``
# containing::
#
#   ``exported_func1``
#   ``exported_func2``
#

# Search for python which is required
if (ABIMap_FIND_REQURIED)
    find_package(PythonInterp REQUIRED)
else()
    find_package(PythonInterp)
endif()


if (PYTHONINTERP_FOUND)
    # Search for abimap tool used to generate the map files
    find_program(ABIMAP_EXECUTABLE NAMES abimap DOC "path to the abimap executable")
    mark_as_advanced(ABIMAP_EXECUTABLE)

    if (NOT ABIMAP_EXECUTABLE AND UNIX)
        message(STATUS "Could not find `abimap` in PATH."
                       " It can be found in PyPI as `abimap`"
                       " (try `pip install abimap`)")
    endif ()

    if (ABIMAP_EXECUTABLE)
        # Get the abimap version
        execute_process(COMMAND ${ABIMAP_EXECUTABLE} version
                        OUTPUT_VARIABLE ABIMAP_VERSION_STRING
                        OUTPUT_STRIP_TRAILING_WHITESPACE)

        # If the version string starts with abimap-, strip it
        if ("abimap" STRLESS_EQUAL ${ABIMAP_VERSION_STRING})
            string(REGEX REPLACE "abimap-" "" ABIMAP_VERSION_STRING "${ABIMAP_VERSION_STRING}")
        endif()
    endif()

    include(FindPackageHandleStandardArgs)
    find_package_handle_standard_args(ABIMap
                                      REQUIRED_VARS ABIMAP_EXECUTABLE
                                      VERSION_VAR ABIMAP_VERSION_STRING)
endif()


if (ABIMAP_FOUND)

# Define helper scripts
set(_EXTRACT_SYMBOLS_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/ExtractSymbols.cmake)
set(_GENERATE_MAP_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/GenerateMap.cmake)
set(_GET_FILES_LIST_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/GetFilesList.cmake)

function(get_file_list _TARGET_NAME)

    set(one_value_arguments
        COPY_TO
    )

    set(multi_value_arguments
        DIRECTORIES
        FILES_PATTERNS
    )

    cmake_parse_arguments(_get_files_list
        ""
        "${one_value_arguments}"
        "${multi_value_arguments}"
        ${ARGN}
    )

    # The DIRS argument is required
    if (NOT DEFINED _get_files_list_DIRECTORIES)
        message(FATAL_ERROR "No directories paths provided. Provide a list of"
                            " directories paths containing header files.")
    endif()

    # The FILES_PATTERNS argument is required
    if (NOT DEFINED _get_files_list_FILES_PATTERNS)
        message(FATAL_ERROR "No matching expressions provided. Provide a list"
                            " of matching patterns for the header files.")
    endif()

    set(_FILES_LIST_OUTPUT_PATH ${CMAKE_CURRENT_BINARY_DIR}/${_TARGET_NAME}.list)

    get_filename_component(_get_files_list_OUTPUT_PATH
                           "${_FILES_LIST_OUTPUT_PATH}"
                           ABSOLUTE)

    add_custom_target(
        ${_TARGET_NAME} ALL
        COMMAND ${CMAKE_COMMAND}
          -DOUTPUT_PATH="${_get_files_list_OUTPUT_PATH}"
          -DDIRECTORIES="${_get_files_list_DIRECTORIES}"
          -DFILES_PATTERNS="${_get_files_list_FILES_PATTERNS}"
          -P ${_GET_FILES_LIST_SCRIPT}
        COMMENT
          "Searching for files"
    )

    set_target_properties(${_TARGET_NAME}
        PROPERTIES LIST_FILE ${_FILES_LIST_OUTPUT_PATH}
    )

    if (DEFINED _get_files_list_COPY_TO)
        # Copy the generated file back to the COPY_TO
        add_custom_target(copy_${_TARGET_NAME} ALL
            COMMAND
              ${CMAKE_COMMAND} -E copy_if_different
              ${_FILES_LIST_OUTPUT_PATH} ${_get_files_list_COPY_TO}
            DEPENDS ${_TARGET_NAME}
            COMMENT "Copying ${_TARGET_NAME} to ${_get_files_list_COPY_TO}"
        )
    endif()

endfunction()

function(extract_symbols _TARGET_NAME)

    set(one_value_arguments
        FILTER_PATTERN
        HEADERS_LIST
        COPY_TO
    )

    set(multi_value_arguments
    )

    cmake_parse_arguments(_extract_symbols
        ""
        "${one_value_arguments}"
        "${multi_value_arguments}"
        ${ARGN}
    )

    # The HEADERS_LIST_FILE argument is required
    if (NOT DEFINED _extract_symbols_HEADERS_LIST)
        message(FATAL_ERROR "No target provided in HEADERS_LIST. Provide a"
                            " target with the property LIST_FILE set as the"
                            " path to the file containing the list of headers.")
    endif()

    get_filename_component(_SYMBOLS_OUTPUT_PATH
                           "${CMAKE_CURRENT_BINARY_DIR}/${_TARGET_NAME}.list"
                           ABSOLUTE
    )

    get_target_property(_HEADERS_LIST_FILE
        ${_extract_symbols_HEADERS_LIST}
        LIST_FILE
    )

    add_custom_target(
        ${_TARGET_NAME} ALL
        COMMAND ${CMAKE_COMMAND}
          -DOUTPUT_PATH="${_SYMBOLS_OUTPUT_PATH}"
          -DHEADERS_LIST_FILE="${_HEADERS_LIST_FILE}"
          -DFILTER_PATTERN=${_extract_symbols_FILTER_PATTERN}
          -P ${_EXTRACT_SYMBOLS_SCRIPT}
        DEPENDS ${_extract_symbols_HEADERS_LIST}
        COMMENT "Extracting symbols from headers"
    )

    set_target_properties(${_TARGET_NAME}
        PROPERTIES LIST_FILE ${_SYMBOLS_OUTPUT_PATH}
    )

    if (DEFINED _extract_symbols_COPY_TO)
        # Copy the generated file back to the COPY_TO
        add_custom_target(copy_${_TARGET_NAME} ALL
            COMMAND
              ${CMAKE_COMMAND} -E copy_if_different
              ${_SYMBOLS_OUTPUT_PATH} ${_extract_symbols_COPY_TO}
            DEPENDS "${_TARGET_NAME}"
            COMMENT "Copying ${_TARGET_NAME} to ${_extract_symbols_COPY_TO}"
        )
    endif()
endfunction()

function(generate_map_file _TARGET_NAME)

    set(options
        FINAL
        BREAK_ABI
    )

    set(one_value_arguments
        RELEASE_NAME_VERSION
        SYMBOLS
        CURRENT_MAP
        COPY_TO
    )

    set(multi_value_arguments
    )

    cmake_parse_arguments(_generate_map_file
        "${options}"
        "${one_value_arguments}"
        "${multi_value_arguments}"
        ${ARGN}
    )

    if (NOT DEFINED _generate_map_file_SYMBOLS)
        message(FATAL_ERROR "No target provided in SYMBOLS. Provide a target"
                            " with the property LIST_FILE set as the path to"
                            " the file containing the list of symbols.")
    endif()

    if (NOT DEFINED _generate_map_file_RELEASE_NAME_VERSION)
        message(FATAL_ERROR "Release name and version not provided."
          " (e.g. libname_1_0_0)")
    endif()


    get_target_property(_SYMBOLS_FILE
        ${_generate_map_file_SYMBOLS}
        LIST_FILE
    )

    # Set generated map file path
    get_filename_component(_MAP_OUTPUT_PATH
                           "${CMAKE_CURRENT_BINARY_DIR}/${_TARGET_NAME}"
                           ABSOLUTE
    )

    add_custom_target(
        ${_TARGET_NAME} ALL
        COMMAND ${CMAKE_COMMAND}
          -DABIMAP_EXECUTABLE=${ABIMAP_EXECUTABLE}
          -DSYMBOLS="${_SYMBOLS_FILE}"
          -DCURRENT_MAP=${_generate_map_file_CURRENT_MAP}
          -DOUTPUT_PATH="${_MAP_OUTPUT_PATH}"
          -DFINAL=${_generate_map_file_FINAL}
          -DBREAK_ABI=${_generate_map_file_BREAK_ABI}
          -DRELEASE_NAME_VERSION=${_generate_map_file_RELEASE_NAME_VERSION}
          -P ${_GENERATE_MAP_SCRIPT}
        DEPENDS ${_generate_map_file_SYMBOLS}
        COMMENT "Generating the map ${_TARGET_NAME}"
    )

    # Add a custom command setting the map as OUTPUT to allow it to be added as
    # a generated source
    add_custom_command(
        OUTPUT ${_MAP_OUTPUT_PATH}
        DEPENDS ${_TARGET_NAME}
    )

    if (DEFINED _generate_map_file_COPY_TO)
        # Copy the generated map back to the COPY_TO
        add_custom_target(copy_${_TARGET_NAME} ALL
            COMMAND
              ${CMAKE_COMMAND} -E copy_if_different ${_MAP_OUTPUT_PATH}
              ${_generate_map_file_COPY_TO}
            DEPENDS ${_TARGET_NAME}
            COMMENT "Copying ${_MAP_OUTPUT_PATH} to ${_generate_map_file_COPY_TO}"
        )
    endif()
endfunction()

endif (ABIMAP_FOUND)