1# 2# Copyright (c) 2017, Alliance for Open Media. All rights reserved 3# 4# This source code is subject to the terms of the BSD 2 Clause License and the 5# Alliance for Open Media Patent License 1.0. If the BSD 2 Clause License was 6# not distributed with this source code in the LICENSE file, you can obtain it 7# at www.aomedia.org/license/software. If the Alliance for Open Media Patent 8# License 1.0 was not distributed with this source code in the PATENTS file, you 9# can obtain it at www.aomedia.org/license/patent. 10# 11if(AOM_DOCS_CMAKE_) 12 return() 13endif() # AOM_DOCS_CMAKE_ 14set(AOM_DOCS_CMAKE_ 1) 15 16cmake_minimum_required(VERSION 3.5) 17 18set(AOM_DOXYFILE "${AOM_CONFIG_DIR}/doxyfile") 19set(AOM_DOXYGEN_CONFIG_TEMPLATE "libs.doxy_template") 20set(AOM_DOXYGEN_OUTPUT_DIR "${AOM_CONFIG_DIR}/dox") 21set(AOM_DOXYGEN_SECTIONS "av1") 22 23set(AOM_DOXYGEN_SOURCES "${AOM_ROOT}/aom/aom.h" "${AOM_ROOT}/aom/aom_codec.h" 24 "${AOM_ROOT}/aom/aom_decoder.h" 25 "${AOM_ROOT}/aom/aom_encoder.h" 26 "${AOM_ROOT}/aom/aom_frame_buffer.h" 27 "${AOM_ROOT}/aom/aom_image.h" 28 "${AOM_ROOT}/aom/aom_integer.h" 29 "${AOM_ROOT}/keywords.dox" "${AOM_ROOT}/mainpage.dox" 30 "${AOM_ROOT}/usage.dox") 31 32if(CONFIG_AV1_DECODER) 33 set(AOM_DOXYGEN_EXAMPLE_SOURCES ${AOM_DOXYGEN_EXAMPLE_SOURCES} 34 "${AOM_ROOT}/apps/aomdec.c" 35 "${AOM_ROOT}/examples/decode_to_md5.c" 36 "${AOM_ROOT}/examples/decode_with_drops.c" 37 "${AOM_ROOT}/examples/simple_decoder.c") 38 39 set(AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS ${AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS} 40 "Full featured decoder." 41 "Frame by frame MD5 checksum." 42 "Drops frames while decoding." 43 "Simplified decoder loop.") 44 45 set(AOM_DOXYGEN_SECTIONS ${AOM_DOXYGEN_SECTIONS} "av1_decoder decoder") 46 47 set(AOM_DOXYGEN_SOURCES ${AOM_DOXYGEN_SOURCES} "${AOM_ROOT}/aom/aomdx.h" 48 "${AOM_ROOT}/usage_dx.dox") 49 50 if(CONFIG_ANALYZER) 51 set(AOM_DOXYGEN_EXAMPLE_SOURCES ${AOM_DOXYGEN_EXAMPLE_SOURCES} 52 "${AOM_ROOT}/examples/analyzer.cc") 53 54 set(AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS ${AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS} 55 "Bitstream analyzer.") 56 endif() 57 58 if(CONFIG_INSPECTION) 59 set(AOM_DOXYGEN_EXAMPLE_SOURCES ${AOM_DOXYGEN_EXAMPLE_SOURCES} 60 "${AOM_ROOT}/examples/inspect.c") 61 62 set(AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS ${AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS} 63 "Bitstream inspector.") 64 endif() 65endif() 66 67if(CONFIG_AV1_ENCODER) 68 set(AOM_DOXYGEN_EXAMPLE_SOURCES ${AOM_DOXYGEN_EXAMPLE_SOURCES} 69 "${AOM_ROOT}/apps/aomenc.c" 70 "${AOM_ROOT}/examples/lossless_encoder.c" 71 "${AOM_ROOT}/examples/set_maps.c" 72 "${AOM_ROOT}/examples/simple_encoder.c" 73 "${AOM_ROOT}/examples/twopass_encoder.c") 74 75 set(AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS ${AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS} 76 "Full featured encoder." 77 "Simplified lossless encoder." 78 "Set active and ROI maps." 79 "Simplified encoder loop." 80 "Two-pass encoder loop.") 81 82 set(AOM_DOXYGEN_EXAMPLE_SOURCES ${AOM_DOXYGEN_EXAMPLE_SOURCES} 83 "${AOM_ROOT}/examples/scalable_encoder.c") 84 85 set(AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS ${AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS} 86 "Scalable encoder loop.") 87 88 set(AOM_DOXYGEN_EXAMPLE_SOURCES ${AOM_DOXYGEN_EXAMPLE_SOURCES} 89 "${AOM_ROOT}/examples/svc_encoder_rtc.c") 90 91 set(AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS ${AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS} 92 "Layered encoder for RTC.") 93 94 set(AOM_DOXYGEN_SECTIONS ${AOM_DOXYGEN_SECTIONS} "av1_encoder encoder") 95 96 set(AOM_DOXYGEN_SOURCES ${AOM_DOXYGEN_SOURCES} "${AOM_ROOT}/aom/aomcx.h" 97 "${AOM_ROOT}/usage_cx.dox") 98endif() 99 100if(CONFIG_AV1_DECODER AND CONFIG_AV1_ENCODER) 101 set(AOM_DOXYGEN_EXAMPLE_SOURCES ${AOM_DOXYGEN_EXAMPLE_SOURCES} 102 "${AOM_ROOT}/examples/aom_cx_set_ref.c") 103 104 set(AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS ${AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS} 105 "Set encoder reference frame.") 106endif() 107 108if(CONFIG_AV1_ENCODER) 109 set(AOM_DOXYGEN_EXAMPLE_SOURCES ${AOM_DOXYGEN_EXAMPLE_SOURCES} 110 "${AOM_ROOT}/examples/lightfield_encoder.c") 111 112 set(AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS ${AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS} 113 "Lightfield encoder example.") 114endif() 115 116if(CONFIG_AV1_DECODER) 117 set(AOM_DOXYGEN_EXAMPLE_SOURCES 118 ${AOM_DOXYGEN_EXAMPLE_SOURCES} 119 "${AOM_ROOT}/examples/lightfield_tile_list_decoder.c") 120 121 set(AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS ${AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS} 122 "Lightfield tile list decoder example.") 123endif() 124 125if(CONFIG_AV1_DECODER) 126 set(AOM_DOXYGEN_EXAMPLE_SOURCES ${AOM_DOXYGEN_EXAMPLE_SOURCES} 127 "${AOM_ROOT}/examples/lightfield_decoder.c") 128 129 set(AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS ${AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS} 130 "Lightfield decoder example.") 131endif() 132 133if(CONFIG_AV1_DECODER AND CONFIG_AV1_ENCODER) 134 set(AOM_DOXYGEN_EXAMPLE_SOURCES 135 ${AOM_DOXYGEN_EXAMPLE_SOURCES} 136 "${AOM_ROOT}/examples/lightfield_bitstream_parsing.c") 137 138 set(AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS ${AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS} 139 "Lightfield bitstream parsing example.") 140endif() 141 142# Iterates over list named by $list_name and appends each item to $AOM_DOXYFILE 143# as values assigned to $var_name with no line breaks between list items. 144# Appends a new line after the entire config variable is expanded. 145function(write_cmake_list_to_doxygen_config_var var_name list_name) 146 unset(output_string) 147 foreach(list_item ${${list_name}}) 148 set(output_string "${output_string} ${list_item} ") 149 endforeach() 150 string(STRIP "${output_string}" output_string) 151 file(APPEND "${AOM_DOXYFILE}" "${var_name} += ${output_string}\n") 152endfunction() 153 154function(get_name file_path name_var) 155 get_filename_component(file_basename ${file_path} NAME) 156 get_filename_component(${name_var} ${file_basename} NAME_WE) 157 set(${name_var} ${${name_var}} PARENT_SCOPE) 158endfunction() 159 160function(setup_documentation_targets) 161 162 # Sanity check: the lengths of these lists must match. 163 list(LENGTH AOM_DOXYGEN_EXAMPLE_SOURCES num_sources) 164 list(LENGTH AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS num_descs) 165 if(NOT ${num_sources} EQUAL ${num_descs}) 166 message(FATAL_ERROR "Unqeual example and description totals.") 167 endif() 168 169 # Take the list of examples and produce example_basename.dox for each file in 170 # the list. 171 file(MAKE_DIRECTORY "${AOM_DOXYGEN_OUTPUT_DIR}") 172 foreach(example_file ${AOM_DOXYGEN_EXAMPLE_SOURCES}) 173 unset(example_basename) 174 get_name("${example_file}" "example_name") 175 set(example_dox "${AOM_DOXYGEN_OUTPUT_DIR}/${example_name}.dox") 176 set(dox_string "/*!\\page example_${example_name} ${example_name}\n") 177 set(dox_string "${dox_string} \\includelineno ${example_file}\n*/\n") 178 file(WRITE "${example_dox}" ${dox_string}) 179 set(AOM_DOXYGEN_SOURCES ${AOM_DOXYGEN_SOURCES} "${example_dox}") 180 endforeach() 181 182 # Generate samples.dox, an index page that refers to the example_basename.dox 183 # files that were just created. 184 set(samples_header " 185/*!\\page samples Sample Code 186This SDK includes a number of sample applications. Each sample documents a 187feature of the SDK in both prose and the associated C code. The following 188samples are included: 189") 190 191 set(utils_desc " 192In addition, the SDK contains a number of utilities. Since these utilities are 193built upon the concepts described in the sample code listed above, they are not 194documented in pieces like the samples are. Their source is included here for 195reference. The following utilities are included: 196") 197 198 # Write the description for the samples section. 199 set(samples_dox "${AOM_CONFIG_DIR}/samples.dox") 200 file(WRITE "${samples_dox}" "${samples_header}\n") 201 202 # Iterate over $AOM_DOXYGEN_EXAMPLE_SOURCES and 203 # $AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS and massage example names as required by 204 # AV1's doxygen setup. 205 math(EXPR max_example_index "${num_sources} - 1") 206 foreach(NUM RANGE ${max_example_index}) 207 list(GET AOM_DOXYGEN_EXAMPLE_SOURCES ${NUM} ex_name) 208 get_name("${ex_name}" "ex_name") 209 210 # AV1's doxygen lists aomdec and aomenc as utils apart from the examples. 211 # Save the indexes for another pass. 212 if("${ex_name}" MATCHES "aomdec\|aomenc") 213 set(util_indexes "${util_indexes}" "${NUM}") 214 continue() 215 endif() 216 list(GET AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS ${NUM} ex_desc) 217 file(APPEND "${samples_dox}" " - \\subpage example_${ex_name} ${ex_desc}\n") 218 endforeach() 219 220 # Write the description and index for the utils. 221 file(APPEND "${samples_dox}" "${utils_desc}\n") 222 foreach(util_index ${util_indexes}) 223 list(GET AOM_DOXYGEN_EXAMPLE_SOURCES ${util_index} ex_name) 224 get_name("${ex_name}" "ex_name") 225 list(GET AOM_DOXYGEN_EXAMPLE_DESCRIPTIONS ${util_index} ex_desc) 226 file(APPEND "${samples_dox}" " - \\subpage example_${ex_name} ${ex_desc}\n") 227 endforeach() 228 file(APPEND "${samples_dox}" "*/") 229 230 # Add $samples_dox to the doxygen inputs. 231 get_filename_component(samples_dox ${samples_dox} NAME) 232 set(AOM_DOXYGEN_SOURCES ${AOM_DOXYGEN_SOURCES} ${samples_dox}) 233 234 # Generate libaom's doxyfile. 235 file(WRITE "${AOM_DOXYFILE}" "##\n## GENERATED FILE. DO NOT EDIT\n##\n") 236 file(READ "${AOM_ROOT}/${AOM_DOXYGEN_CONFIG_TEMPLATE}" doxygen_template_data) 237 file(APPEND "${AOM_DOXYFILE}" ${doxygen_template_data}) 238 file(APPEND "${AOM_DOXYFILE}" 239 "EXAMPLE_PATH += ${AOM_ROOT} ${AOM_ROOT}/examples\n") 240 file(APPEND "${AOM_DOXYFILE}" 241 "INCLUDE_PATH += ${AOM_CONFIG_DIR} ${AOM_ROOT}\n") 242 file(APPEND "${AOM_DOXYFILE}" 243 "STRIP_FROM_PATH += ${AOM_ROOT} ${AOM_CONFIG_DIR}\n") 244 write_cmake_list_to_doxygen_config_var("INPUT" "AOM_DOXYGEN_SOURCES") 245 write_cmake_list_to_doxygen_config_var("ENABLED_SECTIONS" 246 "AOM_DOXYGEN_SECTIONS") 247 248 # Add the doxygen generation rule. 249 add_custom_target(docs ALL 250 COMMAND "${DOXYGEN_EXECUTABLE}" "${AOM_DOXYFILE}" 251 DEPENDS "${AOM_DOXYFILE}" ${AOM_DOXYGEN_SOURCES} 252 ${AOM_DOXYGEN_EXAMPLE_SOURCES} 253 "${AOM_DOXYGEN_CONFIG_TEMPLATE}" 254 SOURCES "${AOM_DOXYFILE}" ${AOM_DOXYGEN_SOURCES} 255 ${AOM_DOXYGEN_EXAMPLE_SOURCES} 256 "${AOM_DOXYGEN_CONFIG_TEMPLATE}") 257endfunction() 258