196 lines · plain
1.. _header_generation:2 3Generating Public and Internal headers4======================================5 6There are 3 main components of the Headergen. The first component are the YAML7files that contain all the function header information and are separated by8header specification and standard. The second component are the classes that9are created for each component of the function header: macros, enumerations,10types, function, arguments, and objects. The third component is the Python11script that uses the class representation to deserialize YAML files into its12specific components and then reserializes the components into the function13header. The Python script also combines the generated header content with14header definitions and extra macro and type inclusions from the .h.def file.15 16 17Instructions18------------19 20Required Versions:21 - Python Version: 3.822 - PyYAML Version: 5.123 241. Keep full-build mode on when building, otherwise headers will not be25 generated.262. Once the build is complete, enter in the command line within the build27 directory ``ninja check-hdrgen`` to ensure that the integration tests are28 passing.293. Then enter in the command line ``ninja libc`` to generate headers. Headers30 will be in ``build/projects/libc/include`` or ``build/libc/include`` in a31 runtime build. Sys spec headers will be located in32 ``build/projects/libc/include/sys``.33 34 35To add a function to the YAML files, you can either manually enter it in the36YAML file corresponding to the header it belongs to or add it through the37command line.38 39To add through the command line:40 411. Make sure you are in the llvm-project directory.42 432. Enter in the command line:44 45 .. code-block:: none46 47 python3 libc/utils/hdrgen/yaml_to_classes.py48 libc/include/[yaml_file.yaml] --add_function "<return_type>" <function_name> "<function_arg1, function_arg2>" <standard> <guard> <attribute>49 50 Example:51 52 .. code-block:: none53 54 python3 libc/utils/hdrgen/yaml_to_classes.py55 libc/include/ctype.yaml --add_function "char" example_function56 "int, void, const void" stdc example_float example_attribute57 58 Keep in mind only the return_type and arguments have quotes around them. If59 you do not have any guards or attributes you may enter "null" for both.60 613. Check the YAML file that the added function is present. You will also get a62 generated header file with the new addition in the hdrgen directory to63 examine.64 65If you want to sort the functions alphabetically you can check out66``libc/utils/hdrgen/hdrgen/yaml_functions_sorted.py``.67 68 69Testing70-------71 72Headergen has an integration test that you may run once you have configured73your CMake within the build directory. In the command line, enter the74following: ``ninja check-hdrgen``. The integration test is one test that75ensures the process of YAML to classes to generate headers works properly. If76there are any new additions on formatting headers, make sure the test is77updated with the specific addition.78 79Integration Test can be found in: ``libc/utils/hdrgen/tests/test_integration.py``80 81File to modify if adding something to formatting:82``libc/utils/hdrgen/tests/expected_output/test_header.h``83 84 85Common Errors86-------------871. Missing function specific component88 89 Example:90 91 .. code-block:: none92 93 "/llvm-project/libc/utils/hdrgen/hdrgen/yaml_to_classes.py", line 67, in yaml_to_classes function_data["return_type"]94 95 If you receive this error or any error pertaining to96 ``function_data[function_specific_component]`` while building the headers97 that means the function specific component is missing within the YAML files.98 Through the call stack, you will be able to find the header file which has99 the issue. Ensure there is no missing function specific component for that100 YAML header file.101 1022. CMake Error: require argument to be specified103 104 Example:105 106 .. code-block:: none107 108 CMake Error at:109 /llvm-project/libc/cmake/modules/LLVMLibCHeaderRules.cmake:86 (message):110 'add_gen_hdr' rule requires GEN_HDR to be specified.111 Call Stack (most recent call first):112 /llvm-project/libc/include/CMakeLists.txt:22 (add_gen_header)113 /llvm-project/libc/include/CMakeLists.txt:62 (add_header_macro)114 115 If you receive this error, there is a missing YAML file, h_def file, or116 header name within the ``libc/include/CMakeLists.txt``. The last line in the117 error call stack will point to the header where there is a specific component118 missing. Ensure the correct style and required files are present:119 120 | ``[header_name]``121 | ``[../libc/include/[yaml_file.yaml]``122 | ``[header_name.h]``123 | ``DEPENDS``124 | ``{Necessary Depend Files}``125 1263. Command line: expected arguments127 128 Example:129 130 .. code-block:: none131 132 usage: yaml_to_classes.py [-h] [--output_dir OUTPUT_DIR] [--h_def_file H_DEF_FILE]133 [--add_function RETURN_TYPE NAME ARGUMENTS STANDARDS GUARD ATTRIBUTES]134 [--e ENTRY_POINTS]135 yaml_file136 yaml_to_classes.py:137 error: argument --add_function: expected 6 arguments138 139 In the process of adding a function, you may run into an issue where the140 command line is requiring more arguments than what you currently have. Ensure141 that all components of the new function are filled. Even if you do not have a142 guard or attribute, make sure to put null in those two areas.143 1444. Object has no attribute145 146 Example:147 148 .. code-block:: none149 150 File "/llvm-project/libc/utils/hdrgen/hdrgen/header.py", line 60, in __str__ for151 function in self.functions: AttributeError: 'HeaderFile' object has no152 attribute 'functions'153 154 When running ``ninja libc`` in the build directory to generate headers you155 may receive the error above. Essentially this means that in156 ``libc/utils/hdrgen/hdrgen/header.py`` there is a missing attribute named functions.157 Make sure all function components are defined within this file and there are158 no missing functions to add these components.159 1605. Unknown type name161 162 Example:163 164 .. code-block:: none165 166 /llvm-project/build/projects/libc/include/sched.h:20:25: error: unknown type167 name 'size_t'; did you mean 'time_t'?168 20 | int_sched_getcpucount(size_t, const cpu_set_t*) __NOEXCEPT169 | ^170 /llvm-project/build/projects/libc/include/llvm-libc-types/time_t.h:15:24:171 note: 'time_t' declared here172 15 | typedef __INT64_TYPE__ time_t;173 | ^174 175 During the header generation process errors like the one above may occur176 because there are missing types for a specific header file. Check the YAML177 file corresponding to the header file and make sure all the necessary types178 that are being used are input into the types as well. Delete the specific179 header file from the build folder and re-run ``ninja libc`` to ensure the180 types are being recognized.181 1826. Test Integration Errors183 184 Sometimes the integration test will fail but that185 still means the process is working unless the comparison between the output186 and expected_output is not showing. If that is the case make sure in187 ``libc/utils/hdrgen/tests/test_integration.py`` there are no missing arguments188 that run through the script.189 190 If the integration tests are failing due to mismatching of lines or small191 errors in spacing that is nothing to worry about. If this is happening while192 you are making a new change to the formatting of the headers, then193 ensure the expected output file194 ``libc/utils/hdrgen/tests/expected_output/test_header.h`` has the changes you195 are applying.196