mirror of
https://github.com/apple/swift.git
synced 2025-12-14 20:36:38 +01:00
364 lines
12 KiB
Python
Executable File
364 lines
12 KiB
Python
Executable File
#!/usr/bin/env python3
|
|
|
|
# This tool dumps imported Swift APIs to help validate changes in the
|
|
# projection of (Objective-)C APIs into Swift, which is a function of the
|
|
# (Objective-)C APIs, any API notes added on top of those APIs, and the
|
|
# Clang importer itself. One can execute it to dump the API of a given
|
|
# module within a particular SDK, e.g., UIKit from the iOS SDK as seen in
|
|
# Swift 4 compatibility mode:
|
|
#
|
|
# /path/to/bin/dir/swift-api-dump.py -swift-version 4 -o output-dir \
|
|
# -m UIKit -s iphoneos
|
|
#
|
|
# The "-m" argument can be omitted, in which case the script will collect
|
|
# all of the frameworks in the named SDK(s) and dump their APIs.
|
|
#
|
|
# One can supply multiple SDKs, written as a list. For example, to
|
|
# dump the API for all frameworks across macOS, iOS, watchOS, and tvOS,
|
|
# in Swift 4.2, use:
|
|
#
|
|
# /path/to/bin/dir/swift-api-dump.py -swift-version 4.2 -o output-dir \
|
|
# -s macosx iphoneos watchos appletvos
|
|
#
|
|
|
|
import argparse
|
|
import multiprocessing
|
|
import os
|
|
import re
|
|
import subprocess
|
|
import sys
|
|
|
|
DEFAULT_TARGET_BASED_ON_SDK = {
|
|
'macosx': 'x86_64-apple-macosx10.11',
|
|
'iphoneos': 'arm64-apple-ios9.0',
|
|
'iphonesimulator': 'x86_64-apple-ios9.0',
|
|
'watchos': 'armv7k-apple-watchos2.0',
|
|
'watchos.simulator': 'i386-apple-watchos2.0',
|
|
'appletvos': 'arm64-apple-tvos9',
|
|
'appletvos.simulator': 'x86_64-apple-tvos9',
|
|
}
|
|
|
|
SKIPPED_FRAMEWORKS = {
|
|
'AppKitScripting',
|
|
'CalendarStore',
|
|
'CoreMIDIServer',
|
|
'DrawSprocket',
|
|
'DVComponentGlue',
|
|
'InstallerPlugins',
|
|
'InstantMessage',
|
|
'JavaFrameEmbedding',
|
|
'JavaVM',
|
|
'Kerberos',
|
|
'Kernel',
|
|
'LDAP',
|
|
'Message',
|
|
'PCSC',
|
|
'PubSub',
|
|
'QTKit',
|
|
'QuickTime',
|
|
'Ruby',
|
|
'Scripting',
|
|
'SyncServices',
|
|
'System',
|
|
'Tk',
|
|
'VideoDecodeAcceleration',
|
|
'vecLib',
|
|
}
|
|
|
|
|
|
def create_parser():
|
|
script_path = os.path.dirname(sys.argv[0])
|
|
script_path = os.path.abspath(script_path)
|
|
default_swift_ide_test = '%s/swift-ide-test' % (script_path)
|
|
|
|
parser = argparse.ArgumentParser(
|
|
description="Dumps imported Swift APIs for a module or SDK",
|
|
prog='swift-api-dump.py',
|
|
usage='%(prog)s -s iphoneos')
|
|
parser.add_argument('-m', '--module', help='The module name.')
|
|
parser.add_argument('-j', '--jobs', type=int,
|
|
help='The number of parallel jobs to execute')
|
|
parser.add_argument('-s', '--sdk', nargs='+',
|
|
required=True, help="The SDKs to use.")
|
|
parser.add_argument('-t', '--target', help="The target triple to use.")
|
|
parser.add_argument('-i', '--swift-ide-test',
|
|
default=default_swift_ide_test,
|
|
help="The swift-ide-test executable.")
|
|
parser.add_argument('-o', '--output-dir', default=os.getcwd(),
|
|
help='Directory to which the output will be emitted.')
|
|
parser.add_argument('-q', '--quiet', action='store_true',
|
|
help='Suppress printing of status messages.')
|
|
parser.add_argument('-v', '--verbose', action='store_true',
|
|
help='Print extra information.')
|
|
parser.add_argument('-F', '--framework-dir', action='append',
|
|
help='Add additional framework directories')
|
|
parser.add_argument('-iframework', '--system-framework-dir',
|
|
action='append',
|
|
help='Add additional system framework directories')
|
|
parser.add_argument('-I', '--include-dir', action='append',
|
|
help='Add additional include directories')
|
|
parser.add_argument('--enable-infer-import-as-member', action='store_true',
|
|
help='Infer when a global could be imported as a ' +
|
|
'member.')
|
|
parser.add_argument('--enable-experimental-concurrency', action='store_true',
|
|
help='Enable experimental concurrency model.')
|
|
parser.add_argument('--enable-experimental-distributed', action='store_true',
|
|
help='Enable experimental distributed actors.')
|
|
parser.add_argument('--enable-experimental-observation', action='store_true',
|
|
help='Enable experimental observation.')
|
|
parser.add_argument('--enable-synchronization', action='store_true',
|
|
help='Enable Synchronization.')
|
|
parser.add_argument('--enable-volatile', action='store_true',
|
|
help='Enable Volatile.')
|
|
parser.add_argument('-swift-version', metavar='N',
|
|
help='the Swift version to use')
|
|
parser.add_argument('-show-overlay', action='store_true',
|
|
help='Show overlay API in addition to Objective-C ' +
|
|
'module API')
|
|
parser.add_argument('-show-doc-comments', action='store_true',
|
|
help='Show documentation comments')
|
|
parser.add_argument('-show-unavailable', action='store_true',
|
|
help='Show declarations that are unavailable in Swift')
|
|
return parser
|
|
|
|
|
|
def output_command_result_to_file(command_args, filename):
|
|
with open(filename, 'w') as output_file:
|
|
subprocess.call(command_args, stdout=output_file)
|
|
|
|
|
|
def run_command(args):
|
|
proc = subprocess.Popen(
|
|
args, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
|
|
out, err = proc.communicate()
|
|
out = out.decode('UTF8')
|
|
exitcode = proc.returncode
|
|
return (exitcode, out, err)
|
|
|
|
# Collect the set of submodules for the given module.
|
|
|
|
|
|
def collect_submodules(common_args, module):
|
|
# Execute swift-ide-test to print the interface.
|
|
my_args = ['-module-print-submodules', '-module-to-print=%s' % (module)]
|
|
(exitcode, out, _) = run_command(common_args + my_args)
|
|
if exitcode != 0:
|
|
print(
|
|
'error: submodule collection failed for module %s with error %d' %
|
|
(module, exitcode))
|
|
return ()
|
|
|
|
# Find all of the submodule imports.
|
|
import_matcher = re.compile(r'.*import\s+%s\.([A-Za-z_0-9.]+)' % (module))
|
|
submodules = set()
|
|
for line in out.splitlines():
|
|
match = import_matcher.match(line)
|
|
if match:
|
|
submodules.add(match.group(1))
|
|
|
|
return sorted(list(submodules))
|
|
|
|
# Print out the command we're about to execute
|
|
|
|
|
|
def print_command(cmd, outfile=""):
|
|
retstr = " ".join(cmd)
|
|
if outfile != "":
|
|
retstr += " > " + outfile
|
|
print(retstr)
|
|
|
|
# Dump the API for the given module.
|
|
|
|
|
|
def dump_module_api_star(pack):
|
|
dump_module_api(*pack)
|
|
|
|
|
|
def dump_module_api(cmd, extra_dump_args, output_dir, module, quiet, verbose):
|
|
# Collect the submodules
|
|
submodules = collect_submodules(cmd, module)
|
|
|
|
# Dump the top-level module
|
|
if verbose:
|
|
print("mkdir -p %s/%s" % (output_dir, module))
|
|
subprocess.call(['mkdir', '-p', ('%s/%s' % (output_dir, module))])
|
|
output_file = '%s/%s/%s.swift' % (output_dir, module, module)
|
|
if not quiet:
|
|
print('Writing %s...' % output_file)
|
|
|
|
top_level_cmd = cmd + extra_dump_args + ['-module-to-print=%s' % (module)]
|
|
if verbose:
|
|
print_command(top_level_cmd, output_file)
|
|
|
|
output_command_result_to_file(top_level_cmd, output_file)
|
|
|
|
# Dump each submodule.
|
|
for submodule in submodules:
|
|
output_file = '%s/%s/%s.swift' % (output_dir, module, submodule)
|
|
if not quiet:
|
|
print('Writing %s...' % output_file)
|
|
|
|
full_submodule = '%s.%s' % (module, submodule)
|
|
submodule_cmd = cmd + extra_dump_args
|
|
submodule_cmd = submodule_cmd + \
|
|
['-module-to-print=%s' % (full_submodule)]
|
|
if verbose:
|
|
print_command(submodule_cmd, output_file)
|
|
|
|
output_command_result_to_file(submodule_cmd, output_file)
|
|
|
|
return
|
|
|
|
|
|
def pretty_sdk_name(sdk):
|
|
if sdk.find("macosx") == 0:
|
|
return 'macOS'
|
|
if sdk.find("iphoneos") == 0:
|
|
return 'iOS'
|
|
if sdk.find("watchos") == 0:
|
|
return 'watchOS'
|
|
if sdk.find("appletvos") == 0:
|
|
return 'tvOS'
|
|
return 'unknownOS'
|
|
|
|
# Collect the set of frameworks we should dump
|
|
|
|
|
|
def collect_frameworks(sdk):
|
|
(exitcode, sdk_path, _) = run_command(
|
|
["xcrun", "--show-sdk-path", "-sdk", sdk])
|
|
if exitcode != 0:
|
|
print('error: framework collection failed to find SDK path for %s '
|
|
'with error %d' % (sdk, exitcode))
|
|
return ()
|
|
sdk_path = sdk_path.rstrip()
|
|
|
|
(exitcode, sdk_version, _) = run_command(
|
|
["xcrun", "--show-sdk-version", "-sdk", sdk])
|
|
if exitcode != 0:
|
|
print('error: framework collection failed to find SDK version for %s '
|
|
'with error %d' % (sdk, exitcode))
|
|
return ()
|
|
sdk_version = sdk_version.rstrip()
|
|
|
|
print('Collecting frameworks from %s %s at %s' %
|
|
(pretty_sdk_name(sdk), sdk_version, sdk_path))
|
|
|
|
# Collect all of the framework names
|
|
frameworks_dir = '%s/System/Library/Frameworks' % sdk_path
|
|
framework_matcher = re.compile(r'([A-Za-z_0-9.]+)\.framework')
|
|
frameworks = set()
|
|
for entry in os.listdir(frameworks_dir):
|
|
match = framework_matcher.match(entry)
|
|
if match:
|
|
framework = match.group(1)
|
|
if framework not in SKIPPED_FRAMEWORKS:
|
|
frameworks.add(framework)
|
|
|
|
return (sorted(list(frameworks)), sdk_path)
|
|
|
|
|
|
def get_short_sdk_name(sdk):
|
|
matched = re.match("[a-zA-Z]+", sdk)
|
|
return matched.group(0)
|
|
|
|
|
|
def create_dump_module_api_args(cmd_common, cmd_extra_args, sdk, module,
|
|
target, output_dir, quiet, verbose):
|
|
|
|
# Determine the SDK root and collect the set of frameworks.
|
|
(frameworks, sdk_root) = collect_frameworks(sdk)
|
|
|
|
# Figure out the "short" name of the SDK
|
|
short_sdk_name = get_short_sdk_name(sdk)
|
|
|
|
# Determine the default target.
|
|
if target:
|
|
sdk_target = target
|
|
else:
|
|
sdk_target = DEFAULT_TARGET_BASED_ON_SDK[short_sdk_name]
|
|
|
|
# Determine the output idirectory
|
|
pretty_sdk = pretty_sdk_name(short_sdk_name)
|
|
sdk_output_dir = '%s/%s' % (output_dir, pretty_sdk)
|
|
|
|
# Create the sets of arguments to dump_module_api.
|
|
results = []
|
|
cmd = cmd_common + ['-sdk', sdk_root, '-target', sdk_target]
|
|
if module:
|
|
results.append(
|
|
(cmd, cmd_extra_args, sdk_output_dir, module, quiet, verbose))
|
|
else:
|
|
for framework in frameworks:
|
|
results.append(
|
|
(cmd, cmd_extra_args, sdk_output_dir, framework, quiet,
|
|
verbose))
|
|
|
|
return results
|
|
|
|
|
|
def main():
|
|
source_filename = 'swift-api-dump.swift'
|
|
parser = create_parser()
|
|
args = parser.parse_args()
|
|
|
|
cmd_common = [
|
|
args.swift_ide_test,
|
|
'-print-module',
|
|
'-source-filename',
|
|
source_filename,
|
|
'-skip-overrides'
|
|
]
|
|
|
|
# Add -module-print-skip-overlay
|
|
if not args.show_overlay:
|
|
cmd_common += ['-module-print-skip-overlay']
|
|
|
|
# Add -skip-print-doc-comments
|
|
if not args.show_doc_comments:
|
|
cmd_common += ['-skip-print-doc-comments']
|
|
|
|
# Add -skip-unavailable
|
|
if not args.show_unavailable:
|
|
cmd_common += ['-skip-unavailable']
|
|
|
|
# Add -F / -iframework / -I arguments.
|
|
if args.framework_dir:
|
|
for path in args.framework_dir:
|
|
cmd_common = cmd_common + ['-F', path]
|
|
if args.system_framework_dir:
|
|
for path in args.system_framework_dir:
|
|
cmd_common = cmd_common + ['-iframework', path]
|
|
if args.include_dir:
|
|
for path in args.include_dir:
|
|
cmd_common = cmd_common + ['-I', path]
|
|
|
|
# Determine the set of extra arguments we'll use.
|
|
extra_args = ['-skip-imports']
|
|
if args.enable_experimental_concurrency:
|
|
extra_args = extra_args + ['-enable-experimental-concurrency']
|
|
if args.swift_version:
|
|
extra_args = extra_args + ['-swift-version', '%s' % args.swift_version]
|
|
|
|
# Create a .swift file we can feed into swift-ide-test
|
|
subprocess.call(['touch', source_filename])
|
|
|
|
# Construct the set of API dumps we should perform.
|
|
jobs = []
|
|
for sdk in args.sdk:
|
|
jobs = jobs + create_dump_module_api_args(
|
|
cmd_common, extra_args, sdk, args.module,
|
|
args.target, args.output_dir,
|
|
args.quiet, args.verbose)
|
|
|
|
# Execute the API dumps
|
|
pool = multiprocessing.Pool(processes=args.jobs)
|
|
pool.map(dump_module_api_star, jobs)
|
|
|
|
# Remove the .swift file we fed into swift-ide-test
|
|
subprocess.call(['rm', '-f', source_filename])
|
|
|
|
|
|
if __name__ == '__main__':
|
|
main()
|