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