• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1#!/usr/bin/python3
2#
3# Copyright 2016-2023 The Khronos Group Inc.
4#
5# SPDX-License-Identifier: Apache-2.0
6"""This script builds a full release package including XHTML and PDF
7versions of the specification, including an optional list of
8extensions. Other files in the release directory are removed,
9including man pages, XHTML chunked, HTML, validity output, etc.
10
11The current branch must be fully committed and up to date when the
12script is run, with no outstanding un-added / un-committed files.
13After completing the build, suggestions for creating tags are made."""
14
15import time
16from datetime import date, timedelta
17
18
19def releaseNum():
20    """Return the Vulkan release number, used for tags."""
21    return '$REVISION'
22
23
24def buildOnFriday():
25    """Return a date for the current, or upcoming if not already, Friday,
26    which is when releases happen."""
27    today = date.today()
28    friday = today + timedelta((4 - today.weekday()) % 7)
29    return friday
30
31
32def buildRelease(label,
33                 versions,
34                 extensions,
35                 ratified,
36                 outdir,
37                 apititle,
38                 xmlDir, xmlTargets,
39                 specDir, specTargets,
40                 miscSrc=None, miscDst=None, needRefSources=False):
41    """Build a release.
42
43    - `label` = textual label to use for target being generated
44    - `versions` = list of core API versions to include
45    - `extensions` = list of extension names to include
46    - `ratified` = True if this is a ratified spec (one built without non-KHR extensions)
47    - `outdir` = directory to generate specs in
48    - `apititle` = extra title to apply to the specification
49    - `xmlDir` = directory containing registry XML
50    - `xmlTargets` = targets to build in xml/
51    - `specDir` = directory containing spec source & Makefile
52    - `specTargets` = targets to build
53    - `miscSrc` = path to copy misc files from, if non-None
54    - `miscDst` = path to copy misc files to, if non-None
55    - `needRefSources` = True if ref pages must be extracted from the spec sources"""
56
57    print('echo Info: Generating target=' + label,
58          'outdir=' + outdir)
59
60    outarg = 'OUTDIR=' + outdir
61
62    if versions != None and len(versions) > 0:
63        versarg = 'VERSIONS="' + ' '.join(versions) + '"'
64    else:
65        versarg = ''
66
67    if extensions != None and len(extensions) > 0:
68        extarg = 'EXTENSIONS="' + ' '.join(extensions) + '"'
69    else:
70        extarg = ''
71
72    if ratified:
73        ratifiedarg = 'EXTRAATTRIBS="-a ratified_core_spec"'
74    else:
75        ratifiedarg = ''
76
77    if apititle != None:
78        titlearg = 'APITITLE="' + apititle + '"'
79    else:
80        titlearg = ''
81
82    # print('echo Info: Creating directory and cleaning spec in', outdir)
83    print('mkdir -p', outdir)
84    print('(cd ', outdir, '&& rm -rf',
85          'html chunked pdf',
86          'man config checks',
87          'vkspec.html styleguide.html apispec.html apispec.pdf registry.html',
88          ')')
89
90    if xmlTargets != '':
91        # print('echo Info: Generating headers and spec include files')
92        print('cd', xmlDir)
93        print('make', outarg, xmlTargets)
94
95    # print('echo Info: Generating ref pages sources and spec targets')
96    print('cd', specDir)
97    print('make', outarg, 'clean')
98    # This is a temporary workaround for a dependency bug - if any of the
99    # specTargets require ref page sources, and they are not already present
100    # at the time the make is invoked, that target will not be built.
101    if needRefSources:
102        print('make', outarg, versarg, extarg, 'refpages')
103    # Now make the actual targets.
104    print('make -O -k -j 8',
105          outarg, versarg, extarg, ratifiedarg, titlearg,
106          'NOTEOPTS="-a implementation-guide"',
107          specTargets)
108
109    if miscSrc != None and miscDst != None:
110        print('mkdir -p', miscDst)
111        print('cp', miscSrc + '/*.adoc', miscDst + '/')
112
113    print('')
114
115
116def buildBranch(targetDir = '',
117                versions = '',
118                extensions = '',
119                ratified = False,
120                apititle = '(NO TITLE SPECIFIED)',
121                xmlTargets = '',
122                specTargets = '',
123                repoDir = '',
124                outDir = '',
125                needRefSources=False):
126    """Build all target documents.
127
128    - `repoDir` = path to the Vulkan git repo containing the specs
129    - `outDir` = path to the output base directory in which targets are generated"""
130
131    # Directory with vk.xml and generation tools
132    xmlDir = repoDir + '/xml'
133    # Directory with spec sources
134    specDir = repoDir
135    # Directory containing misc. files to copy to registry.
136    # At present there are none, since GLSL extensions have moved to the
137    # GLSL repository and are redirected from the Vulkan registry website.
138    # These should be relative to repoDir and outDir, respectively
139    miscSrc = None
140    miscDst = None
141
142    buildRelease(targetDir,
143                 versions,
144                 extensions,
145                 ratified,
146                 outDir + '/' + targetDir,
147                 apititle,
148                 xmlDir, xmlTargets,
149                 specDir, specTargets,
150                 miscSrc, miscDst,
151                 needRefSources)
152
153
154def createTags(releaseNum, tagdate):
155    """Print commands to tag the git branches.
156
157    - `releaseNum` = release number of this spec update, to tag the tree with
158    - `tagdate` = date (used to be used to tag the tree with)"""
159    # Tag date in YYYYMMDD format
160    now = tagdate.strftime('%Y%m%d')
161
162    print('echo To tag the spec branch for this release, execute the command:')
163    print('echo git tag -a -m \\"Tag Vulkan API specification for 1.3.' +
164          releaseNum, 'release\\"', 'v1.3.' + releaseNum)
165