docs/bin/extract_logs_hierarchy.pl

   1 #!/usr/bin/env perl
   2
   3 # Copyright (c) 2008-2022. The SimGrid Team. All rights reserved.
   4
   5 # This program is free software; you can redistribute it and/or modify it
   6 # under the terms of the license (GNU LGPL) which comes with this package.
   7
   8 use strict;
   9 use warnings;
  10
  11 my $debug = 0;
  12
  13 print ".. Generated file, do not edit \n\n";
  14 print ".. _logging_categories:\n\n";
  15 print "Existing categories\n";
  16 print "===================\n\n";
  17 print "This is the list of all categories existing in the SimGrid implementation. "
  18   ."Some of them only exist with specific compile-time options, while your implementation may add new ones. "
  19   ."Please add \`\`--help-log-categories\`\` to the command-line of a SimGrid simulator to see the exact list of categories usable with it.\n\n";
  20
  21 # Search for calls to macros defining new channels, and prepare the tree representation
  22 my %ancestor;
  23 my %desc;
  24 # $ancestor{"toto"} is the ancestor of the toto channel as declared by XBT_LOG_NEW_SUBCATEGORY and
  25 # XBT_LOG_NEW_DEFAULT_SUBCATEGORY ie, when the channel toto is initialized (does not work under windows)
  26
  27 # $desc{"toto"} is its description
  28
  29 sub cleanup_ctn {
  30     my $ctn = shift;        # cleanup the content of a macro call
  31     $ctn =~ s/^\s*(.*)\s*$/$1/gs;
  32     my @elms;
  33     print STDERR "ctn=$ctn\n" if $debug > 1;
  34     if ($ctn =~ m/^(\w+)\s*,\s*(\w+)\s*,\s*"?([^"]*)"?$/s) {
  35         # Perfect, we got 0->name; 1->anc; 2->desc
  36         $elms[0] = $1;
  37         $elms[1] = $2;
  38         $elms[2] = $3;
  39     } elsif ($ctn =~ m/^(\w+)\s*,\s*"?([^"]*)"?$/s) {
  40         # Mmm. got no ancestor. Add the default one.
  41         $elms[0] = $1;
  42         $elms[1] = "XBT_LOG_ROOT_CAT";
  43         $elms[2] = $2;
  44     } else {
  45         die "Unparsable content: $ctn\n";
  46     }
  47     $elms[2] =~ s/\\\\/\\/gs;
  48     return @elms;
  49 }
  50
  51 sub parse_file {
  52     my $filename = shift;
  53
  54     my $data = "";
  55
  56     print STDERR "Parse $filename\n" if $debug;
  57     open IN, "$filename" || die "Cannot read $filename: $!\n";
  58     while (<IN>) {
  59         $data .= $_;
  60     }
  61     close IN;
  62
  63     # Purge $data from C and C++ comments
  64     $data =~ s|/\*.*?\*/||sg;
  65     $data =~ s|//.*$||mg;
  66
  67     while ($data =~ s/^.*?XBT_LOG_NEW(_DEFAULT)?_(SUB)?CATEGORY\(//s) {
  68         $data =~ s/([^"]*"[^"]*")\)//s || die "unparsable macro: $data";
  69
  70         my ($name,$anc,$desc) = cleanup_ctn($1);
  71
  72         # build the tree, checking for name conflict
  73         die "ERROR: Category name conflict: $name used several times (in $ancestor{$name} and $anc, last time in $filename)\n"
  74            if defined ($ancestor{$name}) && $ancestor{$name} ne $anc && defined ($desc{$name}) && $desc{$name} ne $desc;
  75        $ancestor{$name}=$anc;
  76        $desc{$name}=$desc;
  77
  78        print STDERR " $name -> $anc\n" if $debug;
  79    }
  80 }
  81 # Retrieve all the file names
  82 my $path = $ARGV[0] // "..";
  83 open FILES, "find $path/src/ $path/tools/ $path/include/ -name '*.c' -o -name '*.cpp' |" || die "Cannot search for the source file names: $!\n";
  84 while (my $file=<FILES>) {
  85     chomp $file;
  86     parse_file($file);
  87 }
  88 parse_file("$path/include/xbt/sysdep.h");
  89 close FILES;
  90
  91 # Display the tree, looking for disconnected elems
  92 my %used;
  93
  94 sub display_subtree {
  95     my $name=shift;
  96     my $indent=shift;
  97
  98     $used{$name} = 1;
  99     unless ($name eq "XBT_LOG_ROOT_CAT") { # do not display the root
 100         print "$indent - $name: ".($desc{$name}|| "(undocumented)")."\n";
 101     }
 102
 103     my $state = 0; # 0: before the sublist; 1, within; 2: after
 104     foreach my $cat (grep {$ancestor{$_} eq $name} sort keys %ancestor) {
 105         if ($state == 0) {
 106             $state = 1;
 107             print "\n";
 108         }
 109         display_subtree($cat, $name eq "XBT_LOG_ROOT_CAT" ? $indent: "$indent  ");
 110     }
 111     if ($state != 0) {
 112         print "\n";
 113     }
 114 }
 115
 116 display_subtree("XBT_LOG_ROOT_CAT","");
 117
 118 map {
 119     warn "Category $_ does not seem to be connected to the root (anc=$ancestor{$_})\n";
 120 } grep {!defined $used{$_}} sort keys %ancestor;
 121
 122 print "\n";