Man Linux: Main Page and Category List

NAME

       metalint - a metaconfig unit consistency checker

SYNOPSIS

       metalint [ -hklsV ] [ -L dir ]

DESCRIPTION

       Metalint  parses  the  units  and  performs  some extensive consistency
       checks, to make sure the whole set is sound. Due to the relatively huge
       amount  of  units  available, it is becoming very difficult to maintain
       the units manually, and an automated  process  can  be  of  real  help,
       although not perfect.

       Metalint  operates  from within your top level package directory and is
       used to make sure your own private units are correctly relying  on  the
       publicly  available  units.   If you intensively develop new units, you
       should run metalint on them before making them publicly available.

OPTIONS

       Metalint recognizes the following set of options:

       -h             Print a short usage description and exit.

       -k             Keep temporary .MT directory.

       -l             (not implemented yet) By default, metalint only  reports
                      problems  related to your own private units. This switch
                      directs metalint to also  report  problems  in  publicly
                      available units.

       -s             Silent mode.

       -L dir         Override  default library location. Normally only useful
                      for metaconfig maintainers to locally  check  the  units
                      being developped instead of the publicly available ones.
                      The dir specified is the  one  containing  the  units  U
                      directory.

       -V             Print version number and exit.

DIAGNOSTICS

       The following diagnostics may be emitted by metalint:

       "(?MAKE) ignoring duplicate dependency listing line."
            More  than  one  ?MAKE: line bearing dependencies was found in the
            unit. There may be only one such  line,  although  multiple  ?MAKE
            action lines may occur.

       "(?MAKE) special unit ’Xxx’ should not be listed as made."
            A  special  unit  symbol  (first  letter  capitalized) may only be
            listed as made in  the  special  unit  itself.  To  suppress  this
            warning  in  legitimate cases, add a ’+’ in front of the offending
            symbol (note that for non-special units, the ’+’ in this  position
            indicates  an  internal  symbol  which  should  not  appear in the
            config.sh file).

       "(?MAKE) ’+xxx’ is listed x times."
            A conditional  dependency  is  listed  more  than  once.  This  is
            harmless though.

       "(?MAKE) ’xxx’ is listed x times."
            A  normal depdendency is listed more than once. Again, an harmless
            error.

       "(?MAKE) ’xxx’ listed as both conditional and full dependency."
            Symbol is listed as a normal dependency and as a conditional  one.
            Metaconfig will consider this as being a full dependency, but that
            may not be what you initially wanted...

       "(?Y) unknown layout directive ’xxx’."
            Layout directives may only be one of top, default or  bottom,  but
            case  does  not  matter.  An unknown directive is just ignored and
            handled as if default had been specified.

       "(?S) duplicate description for variable ’$xxx’."
            Shell symbol is described more than once, and  that  will  produce
            two entries in the Glossary.

       "(?S) variable ’$xxx’ is not listed on ?MAKE: line."
            The  unit  describes  a  shell  symbol  entry which cannot be used
            externally since not listed as a dependency.

       "(?S) syntax error in ?S: construct."
            Self explainatory.

       "(?C) duplicate description for symbol ’XXX’."
            C symbol is described more than once, and that  will  produce  two
            entries for it in the Glossary.

       "(?C) syntax error in ?C: construct."
            Self explainatory.

       "(?H) symbol ’XXX’ was already defined."
            Apparently, two ?H: lines are defining the same C symbol.

       "(?H) variable ’$xxx’ not even listed on ?MAKE: line."
            A variable is used, but not listed on the dependency line.

       "(?H) section was already terminated by ’?H:.’."
            There  can be no more ?H: lines after the first ’?H:.’ marking the
            end of that section.

       "(?H) uncommon cpp line should be protected with ’?%<:’."
            All ?H: lines that are recognized by metaconfig and thus  metalint
            have  their  inclusion  in  config.h  automatically protected by a
            suitable symbol if none is provided.  However, unrecognized  lines
            must  be  protected  with  the  ’?%<:’  sequence  to  avoid  their
            inclusion should the unit not be loaded in Configure.

       "(?H) line should not be listed here but in ’?C:’."
            Only cpp lines should appear in the ?H: section.  If  you  have  a
            comment  to  put  regarding  the  symbol, use ?C:.  If you want to
            comment a  particular  generation  sequence,  put  them  into  ?X:
            comment so that they don’t make it into config.h.

       "(?H) constraint ’xxx’ is an unknown symbol."
            All  the  leading  ?sym:  constraints on the ?H: lines should be a
            valid shell or C symbol, defined in the unit.

       "(?M) syntax error in ?M: construct."
            Self explainatory.

       "(?M) symbol ’xxx’ already listed on a ?M: line in ’yyy’."
            A magic definition for symbol xxx is attempted,  but  another  one
            was already provided in unit yyy.

       "(?V) visible declaration in non-special unit ignored."
            Visible declarations (?V: lines) may only appear in special units.
            Otherwise, they are meaningless.

       "(?V) wanted variable ’$xxx’ made visible."
            A wanted variable (described as a dependency on the  ?MAKE:  line)
            cannot  be  made  visible  since that does not make any sense: the
            unit cannot depend on it and then advertise it  as  being  locally
            defined.

       "(?V) defined variable ’$xxx’ made visible."
            A  defined  variable (listed as made on the ?MAKE: line) cannot be
            made visible, since it could as well be directly wanted in another
            unit.

       "(?V) variable ’$xxx’ already made visible by unit yyy."
            Inconsistent  declaration:  two units are making one single symbol
            visible...

       "(?V) variable ’$xxx’ already read-write visible in yyy."
            The variable was already made visible  as  read-write  by  another
            unit.

       "(?V) variable ’$xxx’ already read-only visible in yyy."
            The  variable  was  already  made  visible as read-only by another
            unit.

       "(?W) variable ’$xxx’ already wanted."
            Variable is already wanted, there is no need  to  explicitely  ask
            for it here.

       "(?W) variable ’$xxx’ also locally defined."
            A  wanted  variable would conflict with a locally defined variable
            and could result in getting a garbage value.

       "(?W) variable ’$xxx’ already listed on a ?W: line in ’yyy’."
            The variable in the shell symbol section of a ?W:  line  can  only
            appear in one unit.

       "(?F) produced file ’xxx’ mutiply declared."
            The  file is listed more than once on the ?F: line, under the same
            name.  This does not appear when declaring both a private UU  file
            and a public file with the same name, for instance.

       "(?F) UU file  in non-special unit ignored."
            Private  UU  files  (i.e. files like the myread script created for
            later perusal by Configure) may only be created in special  units.
            Exceptions  allowed if the ?F: line is preceded by a proper ?LINT:
            hint.

       "(?T) temporary symbol ’$xxx’ multiply declared."
            Self explainatory.

       "directive should come after ?MAKE declarations."
            The directive listed between () at the beginning of  this  message
            should  really  come after the ?MAKE: lines.  You must reorder the
            unit or metalint will not be able to properly diagnose problems.

       "control sequence ’?XXX:’ ignored within body."
            Attempt to use a control line other than ?X: or ?LINT: in the unit
            body, which should be only shell code

       "variable ’$xxx’ is changed."
            A  variable  listed  as  wanted in the dependency line is changed.
            Such a variable should be read-only for the unit. Use  the  change
            lint hint to suppress this message in pathological cases.

       "no ?MAKE: line describing dependencies."
            Every  unit  should have a dependency line, or it will be silently
            ignored by metaconfig. This message  is  suppressed  by  a  ?LINT:
            empty hint.

       "first body line should be a general ’: description’."
            The  very  first  shell line of the unit that will be added to the
            generated Configure script should hold a description of the unit’s
            purpose,  on  a  ’:’  line.   There must be a space after the ’:’,
            since it is interpreted by the shell, and the  description  should
            avoid  meta-characters  like ’(’ or ’>’ unless the whole string is
            quoted.  This message is suppressed by a ?LINT: nocomment hint.

       "missing space after ’:’ to make it a comment."
            A line starting by ’:’ is interpreted by the  shell  but  will  be
            ignored.  There must be a space after the ’:’ though, or the shell
            will try to execute an unknown command...

       "found unquoted meta-character > on comment line."
            A line starting by ’:’ is interpreted by the  shell  but  will  be
            ignored.   This  means that meaningful meta-characters such as ’(’
            or ’>’ must be quoted or escaped with a leading backslash.

       "found dangling quote on ’:’ comment line."
            An unclosed single or double quote was spotted on  a  ’:’  comment
            line.   Since  those  lines  are  interpreted by the shell, albeit
            ignored, all quotes must match perfectly.

       "not ending with a blank line."
            Since all units are gathered together to form one big  script,  it
            is  recommended  (hence enforced by metalint) that every unit file
            end with an empty line.

       "last line not ending with a new-line character."
            This is merely intended to users  whose  editor  does  not  always
            append a new-line at the end of text files. Should not happen when
            you use vi.

       "symbol ’$xxx’ was not described."
            The shell symbol defined by this unit was not documented. Use  the
            describe lint hint to suppress this message.

       "C symbol ’XXX’ was not described."
            The  C  symbol  defined  by  this unit was not documented. Use the
            known lint hint to suppress this message.

       "C symbol ’XXX’ was not defined by any ?H: line."
            A C symbol was advertised by never defined, hence it cannot appear
            in the config.h file and is therefore useless...

       "variable ’$xxx’ should have been set."
            A variable listed on the make line as made by the unit was not set
            by the shell code body. Use the set lint  hint  to  suppress  this
            message in pathological cases.

       "unused dependency variable ’$xxx’."
            Apparently  no usage is made from a shell variable. Use the change
            or use lint hints (depending on the situation)  to  suppress  this
            message.

       "unused conditional variable ’$xxx’.
            Apparently  no usage is made from this conditional dependency. The
            change or use lint hints can be used to suppress this message.

       "unused temporary variable ’$xxx’."
            A variable declared as temporary in a ?T: line is  not  used.  The
            use lint hint will fool metalint into thinking it’s indeed used.

       "unknown control sequence ’?XXX:’."
            Attempt to use an unknown control sequence.

       "unknown LINT request ’false’ ignored."
            An  unknown ?LINT: tag was used. All such tags must be spelled out
            in lowercase.

       "symbol ’$xxx’ has no default value."
            A symbol used as a conditional dependency  in  some  unit  has  no
            default value set by a ?D: line.

       "stale ?MAKE: dependency ’xxx’."
            Unit  lists a symbol as a dependency, but that symbol is otherwise
            unknown, i.e.  never appears as made by any other unit.

       "symbol ’$xxx’ missing from ?MAKE."
            A symbol used or defined was not listed as  a  dependency  in  the
            ?MAKE: line.

       "missing xxx from ?MAKE for visible ’$yyy’."
            A  symbol  defined  as visible by a special unit is used, but that
            special unit is not part of the dependency line.

       "stale ?M: dependency ’xxx’."
            Magic line lists a C symbol as a dependency but that symbol is not
            known by any unit.

       "unknown symbol ’$xxx’."
            I  have  no  idea  about  what  this symbol is. If the variable is
            externally define, this warning can  be  suppresed  via  a  proper
            ?LINT: extern.

       "read-only symbol ’$xxx’ is set."
            A  symbol that should be read-only is set by the unit’s shell code
            body.

       "obsolete symbol ’xxx’ is used."
            An obsolete symbol is used in the unit’s shell code.

       "undeclared symbol ’$xxx’ is set."
            The unit tries  to  set  a  shell  variable  which  has  not  been
            otherwise  declared  as  made  or  as  a  temporary  variable,  or
            whatever.

       "unclosed ?H: section."
            The ?H: section was not terminated by a single ’?H:.’ line  before
            the body of the unit or the start of another ?C: section.

       "C symbol ’xxx’ is defined in the following units:"
            The C symbol is defined in more that one unit. Offending units are
            listed.

       "Shell symbol ’xxx’ is defined in the following units:"
            A shell symbol is defined in more than one unit.  Offending  units
            folllow.

       "Shell symbol ’xxx’ is altogether:"
            A  shell  symbol is defined by some units, obsoleted by others and
            used as a temporary.

       "Shell symbol ’xxx’ is both defined and obsoleted:"
            Self explainatory.

       "Shell symbol ’xxx’ is both defined and used as temporary:"
            Self explainatory.

       "Shell symbol ’xxx’ obsoleted also used as temporary:"
            Self explainatory.

       "definition of ’$xxx’ not closed by ’?S:.’."
            Self explainatory.

       "definition of ’XXX’ not closed by ’?C:.’."
            Self explainatory.

       "magic definition of ’xxx’ not closed by ’?M:.’."
            Self explainatory.

       "variable ’$xxx’ is defined externally."
            A variable defined externally (i.e.  in  another  unit)  is  used,
            without proper dependency information. Use the extern lint hint to
            suppress this message.

       "file ’xxx’ was not created."
            A file listed as a private UU file is not created by  the  special
            unit.  Creation is detected by seing an explicit shell redirection
            to the file, not by an implicit creation (such as a C  compilation
            would  for  instance).  All special units should create only shell
            scripts explicitely anyway so this message  cannot  be  suppressed
            via a lint hint.

       "local file ’xxx’ may override the one set by ’unit.U’."
            You  are  attempting  to create a local file, but the special unit
            creates one bearing the exact same name and should  it  be  loaded
            before  within Configure, you would override that file. Change the
            name of your local file.

       "unused temporary file ’xxx’.
            The file was declared on the ?F: line but does not  appear  to  be
            used anywhere.

       "mis-used temporary file ’xxx’.
            A  local  temporary  file has been declared on the ?F: line and is
            used in a way that may not be the proper  one.  Indeed,  all  such
            local  files  should  be called with an explicit relative path, to
            avoid PATH lookups which could get you another file.

       "you might not always get file ’xxx’ from ’unit.U’."
            You seem to be calling the specified file, but  not  by  using  an
            explicit  relative pathname. Relying on the PATH to find this file
            is not safe.  To fix this problem, call your file  using  somthing
            like ./xxx.

       "missing Unit from ?MAKE for private file ’xxx’."
            You  are  using a private UU file without listing the special unit
            that produces it in your dependency line. Add  the  unit  to  your
            dependency list.

       "unknown private file ’xxx’."
            The file does not appear on any ?F: line; however it should.

       "File ’xxx’ is defined in the following units:"
            The listed units cannot seem to agree on who is defining the file.

       "empty here-document name discouraged."
            You should refrain from using empty names for here  documents,  as
            metalint will not monitor those.

       "unclosed here-document xxx started line x."
            The  opened here-document at line x was never closed in this unit.
            This generally mean that when the  unit  is  used,  the  generated
            script will not work!

       "spurious ’LINT xxx’ directive."
            You  have  inserted a ?LINT: directive that is not used to shut-up
            warnings.

       "Cycle found for:"
            There is a dependency cycle found for the symbols listed. Only the
            symbols involved in the cycle are listed.

       "Cycle involves:"
            An exerpt of the dependencies where the cycle was found is listed.
            This may involve far  more  symbols  than  the  previous  message,
            because metalint actually rescans the rules to emphasize the cycle
            and stops whenever it has found one,  i.e.  it  does  not  try  to
            minimize  it  (the  cycle  is found using another algorithm, which
            unfortunately cannot spit it out but only say for  sure  there  is
            one).

REFERENCE

       Metalint  uses the following control lines, which are otherwise ignored
       by metaconfig:

       ?V:read-only symbols:read-write symbols
            This line should be used only in special units. It lists  all  the
            shell  variable  defined  by  the  unit  which  should not be used
            directly as dependencies by other units: they  must  include  this
            special  unit  in their dependency list if they make use of any of
            the symbols described  here.  Those  can  be  viewed  as  exported
            symbols  which  you  inherit  from  when  depending from the unit.
            Symbols may be exported read-only or read-write.

       ?F:files created
            This line serves two purposes: it is a metalint hint, and  also  a
            placeholder  for  future  jmake  use.  It  must list three kind of
            files: the temporary one which are created for a test, the private
            UU  ones  created  in  the UU directory for later perusal, and the
            public ones left in the root directory of the  package.  Temporary
            files  must be listed with a preceding ’!’ character (meaning "no!
            they’re not re-used later!"), private UU files should be  preceded
            by  a  ’./’ (meaning: to use them, say ./file, not just file), and
            public ones should be named as-is.

       ?T:shell temporaries
            This line should list all the shell variables used as  temporaries
            within  the  unit’s  body.  This line should be kept accurate, and
            prevents you from writing a unit defining a symbol which would  be
            used as a scratch variable in another unit...

       ?LINT:keyword symbol_list
            Specifies a lint hint. The following keywords are available:

                 change         shell variable ok to be changed
                 create         persistent  file  ok  to  be  created  by non-
                                special unit
                 define         shell variables listed  are  defined  in  this
                                unit
                 describe       listed shell variables are described by ?S:
                 extern         variable known to be externally defined
                 empty          unit   file  is  empty  and  kept  only  as  a
                                placeholder.
                 known          listed C variables are described
                 nocomment      unit file is special and may miss a leading ’:
                                description’ line.
                 nothere        listed  names  are not here documents (e.g. "1
                                << foo" in a C program)
                 set            listed variables are set
                 use            variables listed are used by this unit
                 unclosed       listed names of here-documents are not  closed
                                in this unit
                 usefile        listed  file is used (do not prepend name with
                                ’!’ for temporary ones)

AUTHORS

       Harlan Stenn <harlan@mumps.pfcs.com> wrote the first version, based  on
       Larry Wall’s metaconfig from dist 2.0.
       Raphael Manfredi <ram@hptnos02.grenoble.hp.com> rewrote it from scratch
       for 3.0 with a few enhancements.

FILES

       LIB/dist/mcon/U/*.U
                 Public unit files
       U/*.U     Private unit files

                      where LIB is /usr/share/dist.

BUGS

       Maybe.

SEE ALSO

       metaconfig(1), metaxref(1)

                                Version 3.5 PL0