circular::require(3)

NAME
circular::require - detect circularity in use/require statements

VERSION
version 0.12

SYNOPSIS
  package Foo;
  use Bar;

  package Bar;
  use Foo;

  package main;
  no circular::require;
  use Foo; # warns

or

  perl -M-circular::require foo.pl

DESCRIPTION
Perl by default just ignores cycles in require statements - if Foo.pm does "use Bar" and Bar.pm does "use Foo", doing "use Foo" elsewhere will start loading Foo.pm, then hit the "use" statement, start loading Bar.pm, hit the "use" statement, notice that Foo.pm has already started loading and ignore it, and continue loading Bar.pm. But Foo.pm hasn't finished loading yet, so if Bar.pm uses anything from Foo.pm (which it likely does, if it's loading it), those won't be accessible while the body of Bar.pm is being executed. This can lead to some very confusing errors, especially if introspection is happening at load time ("make_immutable" in Moose classes, for example). This module generates a warning whenever a module is skipped due to being loaded, if that module has not finished executing.

This module works as a pragma, and typically pragmas have lexical scope. Lexical scope doesn't make a whole lot of sense for this case though, because the effect it's tracking isn't lexical (what does it mean to disable the pragma inside of a cycle vs. outside of a cycle? does disabling it within a cycle cause it to always be disabled for that cycle, or only if it's disabled at the point where the warning would otherwise be generated? etc.), but dynamic scope (the scope that, for instance, "local" uses) does, and that's how this module works. Saying "no circular::require" enables the module for the current dynamic scope, and "use circular::require" disables it for the current dynamic scope. Hopefully, this will just do what you mean.

In some situations, other modules might be handling the module loading for you - "use base" and "Class::Load::load_class", for instance. To avoid these modules showing up as the source of cycles, you can use the "-hide" parameter when using this module. For example:

  no circular::require -hide => [qw(base parent Class::Load)];

or

  perl -M'-circular::require -hide => [qw(base parent Class::Load)];' foo.pl

CAVEATS
This module works by overriding "CORE::GLOBAL::require", and so other modules which do this may cause issues if they aren't written properly. See Devel::OverrideGlobalRequire for more information.

BUGS
No known bugs.

Please report any bugs to GitHub Issues at <https://github.com/doy/circular-require/issues>.

SUPPORT
You can find this documentation for this module with the perldoc command.

    perldoc circular::require

You can also look for information at:

•   MetaCPAN

    <https://metacpan.org/release/circular-require>

•   RT: CPAN's request tracker

    <http://rt.cpan.org/NoAuth/Bugs.html?Dist=circular-require>

•   Github

    <https://github.com/doy/circular-require>

•   CPAN Ratings

    <http://cpanratings.perl.org/d/circular-require>

AUTHOR
Jesse Luehrs <doy@tozt.net>

COPYRIGHT AND LICENSE
This software is copyright (c) 2016 by Jesse Luehrs.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.