Home | History | Annotate | Download | only in libchrome_tools 
      1 #!/usr/bin/python
      2 
      3 # Copyright (C) 2018 The Android Open Source Project
      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 """Generates wrapped include files to workaround -Wunused-parameter errors.
     18 
     19 In Chrome repository, "-Wunused-parameter" is disabled, and several header
     20 files in Chrome repository have actually unused-parameter.
     21 One of the typical scenarios is; in Chrome, Observer class is often defined
     22 as follows:
     23 
     24 class Foo {
     25  public:
     26   class Observer {
     27    public:
     28     virtual void OnSomeEvent(EventArg arg) {}
     29     virtual void OnAnotherEvent(EventArg arg) {}
     30     ...
     31   };
     32   ...
     33 };
     34 
     35 Here, On...Event() methods do nothing by default, and subclasses will override
     36 only necessary ones.
     37 In this use case, argument names can also work as documentation, and overrides
     38 can use these good interface-defined default names as a starting point for
     39 their implementation.
     40 
     41 On the other hand, in Android, -Wunused-parameter is enabled by default.
     42 Thus, if such a project includes header files from libchrome, it could cause
     43 a compile error (by the warning and "-Werror").
     44 
     45 To avoid such a situation, libchrome exports include files wrapped by the
     46 pragmas as follows.
     47 
     48 #pragma GCC diagnostic push
     49 #pragma GCC diagnostic ignored "-Wunused-parameter"
     50 ${actual_include_file_content}
     51 #pragma GCC diagnostic pop
     52 
     53 so, the unused-parameter warning generated by the libchrome include headers
     54 will be ignored.
     55 Note that these GCC pragmas are also supported by clang for compatibility. cf)
     56 https://clang.llvm.org/docs/UsersManual.html#controlling-diagnostics-via-pragmas
     57 
     58 Usage: include_generator.py $(in) $(out)
     59 """
     60 
     61 import sys
     62 
     63 
     64 def _generate(input_path, output_path):
     65     """Generates a include file wrapped by pragmas.
     66 
     67     Reads the file at |input_path| and output the content with wrapping by
     68     #pragma to ignore unused-parameter warning into the file at |output_path|.
     69     If the parent directories of |output_path| do not exist, creates them.
     70 
     71     Args:
     72         input_path: Path to the source file. Expected this is a chrome's header
     73             file.
     74         output_path: Path to the output file.
     75     """
     76     with open(input_path, 'r') as f:
     77         content = f.read()
     78 
     79     with open(output_path, 'w') as f:
     80         f.writelines([
     81             '// Generated by %s\n' % sys.argv[0],
     82             '#pragma GCC diagnostic push\n'
     83             '#pragma GCC diagnostic ignored "-Wunused-parameter"\n',
     84             content,
     85             '#pragma GCC diagnostic pop\n'])
     86 
     87 
     88 def main():
     89     _generate(*sys.argv[1:])
     90 
     91 
     92 if __name__ == '__main__':
     93     main()
     94