{"id":19640323,"url":"https://github.com/kentnl/dist-zilla-plugin-lib","last_synced_at":"2025-07-28T23:04:00.136Z","repository":{"id":56835926,"uuid":"80983417","full_name":"kentnl/Dist-Zilla-Plugin-lib","owner":"kentnl","description":"A simpler bootstrap for a more civilised world","archived":false,"fork":false,"pushed_at":"2017-03-06T12:01:39.000Z","size":67,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-09T18:56:40.368Z","etag":null,"topics":["dist-zilla","loading","packaging","perl"],"latest_commit_sha":null,"homepage":null,"language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kentnl.png","metadata":{"files":{"readme":"README.mkdn","changelog":"Changes","contributing":"CONTRIBUTING.pod","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-02-05T09:42:54.000Z","updated_at":"2017-02-05T09:43:21.000Z","dependencies_parsed_at":"2022-09-07T07:10:41.238Z","dependency_job_id":null,"html_url":"https://github.com/kentnl/Dist-Zilla-Plugin-lib","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kentnl%2FDist-Zilla-Plugin-lib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kentnl%2FDist-Zilla-Plugin-lib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kentnl%2FDist-Zilla-Plugin-lib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kentnl%2FDist-Zilla-Plugin-lib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kentnl","download_url":"https://codeload.github.com/kentnl/Dist-Zilla-Plugin-lib/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240947649,"owners_count":19883030,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dist-zilla","loading","packaging","perl"],"created_at":"2024-11-11T14:05:22.412Z","updated_at":"2025-02-26T22:44:39.593Z","avatar_url":"https://github.com/kentnl.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NAME\n\nDist::Zilla::Plugin::lib - A simpler bootstrap for a more civilised world\n\n# VERSION\n\nversion 0.001003\n\n# SYNOPSIS\n\n    name = My-Dist\n    author = Mr CPAN Person \u003cperson@cpan.example.org\u003e\n    license = Perl_5\n    ...\n\n    ; push ./inc into @INC\n    [lib]\n    lib = inc\n\n    ; loads inc/My/GatherDir.pm\n    [=My::GatherDir]\n\n# DESCRIPTION\n\nDist::Zilla::Plugin::lib serves as a relatively straight-forward and\nuncomplicated way to wire certain local paths in your distributions\nsource tree into Perl's `@INC` library load path.\n\nIts primary audiences are twofold.\n\n- Self-Building Dist::Zilla Plugins\n\n    Many recent [Dist::Zilla](https://metacpan.org/pod/Dist::Zilla) plugin workflows champion a\n    state of `lib/` which are usable \"as is\" without needing to cycle\n    through a `dzil build` phase first, and this plugin offers a simple\n    way to stash `lib/` in `@INC` without needing to pass `-Ilib` every\n    time you run `dzil`.\n\n    Workflows that require a build cycle to self-build should use\n    [`[Bootstrap::lib]`](https://metacpan.org/pod/Dist::Zilla::Plugin::Bootstrap::lib) instead.\n\n- Bundled Dist::Zilla Plugins\n\n    Many heavy `CPAN` distributions have bundled within them custom `Dist::Zilla`\n    plugins stashed in `inc/`\n\n    Traditionally, these are loaded via `[=inc::Foo::Package]` exploiting\n    the long held assumption that `\".\"` ( `$CWD` ) is contained in `@INC`\n\n    However, that is becoming a [less safe assumption](#related-reading), and this\n    plugin aims to make such equivalent behaviour practical without needing to\n    rely on that assumption.\n\n# USAGE\n\nInserting a section in your `dist.ini` as follows:\n\n    [lib]\n    lib = some/path\n\n    [=Some::Plugin]\n\n    [Some::Other::Plugin]\n\nWill prepend `some/path` (relative to your distribution root) into\n`@INC`, and allow loading of not just plugins, but plugin dependencies\nfrom the designated path.\n\n`[=Some::Plugin]` will be able to load, as per existing `Dist::Zilla` convention,\nvia `inc/Some/Plugin.pm`, and then fall back to searching other `@INC` paths.\n\n`[Some::Other::Plugin]` will **also** be able to load from `inc/`,\nvia `inc/Dist/Zilla/Plugin/Some/Other/Plugin.pm`\n\n# Ensuring dot-in-INC\n\nIts not sure when `\".\"` in `@INC` will actually go away, or which parts of the `dzil`\necosystem will be re-patched to retain this assumption.\n\nBut the simplest thing that would work with changing the least amount of code would be\nsimply inserting\n\n    [lib]\n    lib = .\n\nEarly in your `dist.ini`\n\nThis will have a `mostly` the same effect as retaining `dot-in-INC` even in the\nevent you run on a newer Perl where that is removed by default.\n\nThe differences however are subtle and maybe better depending on what you're doing\n\n- `\".\"` will be prepended to `@INC`, not appended.\n\n    This means `[=inc::Foo]` will actually hit `inc/` first, not simply as an afterthought\n    if it isn't found in other paths in `@INC`\n\n    For instance, currently, I could create a lot of havoc by simply shipping a `dzil` plugin with\n    the same name as somebody already is using for their private `inc/` hacks, and then trip them\n    into installing it. Because currently, `site beats \".\"` where authors intended to source\n    from `\".\"` not `site`\n\n- `\".\"` will be absolutized to `$zilla-\u003eroot`\n\n    As it stands, the `\".\"` in `@INC` is only ever `\".\"`, which means calling\n    `chdir` between calls to `require` effectively changes what `@INC` means.\n\n    Given that is the specific threat surface for that issue, it would be silly\n    to repeat that mistake, especially as when you write `\".\"` you typically want to\n    imply \"Where I am now\" not \"Wherever the code will be 30 seconds after now after\n    it `chdir`s to random locations at the discretion of code I haven't even read\"\n\n    There's still some annoying scope for this absolutization going wrong,\n    due to `Dist::Zilla` not [ensuring this path is fixed early on](https://github.com/rjbs/Dist-Zilla/issues/579)\n    but `[lib]` fixes and absolutizes it as early as possible,\n    with the hope we'll know what you meant by `cwd` before somebody can change `cwd`\n\n    ( And if that fails, it will fail spectacularly, not selectively work some of the\n    time if your stars align )\n\n# Migrating from dot-in-INC code\n\nIf you have existing code that relies on the `.`-in-`@INC` assumption,\nmigrating to use this plugin in way that would seem \"proper\" would play as follows:\n\n- 1. Rename your plugins in `inc/`\n\n    All those packages called `inc::Some::Plugin` become\n    `Some::Plugin`\n\n- 2. Replace your section lines\n\n    `inc` is no longer needed as part of the plugin, so\n    replacing all sections\n\n        -[=inc::Some::Plugin]\n        +[=Some::Plugin]\n\n    In line with step 1.\n\n- 3. Add a `[lib]` section before all your plugins\n\n    And tell it to assume that `inc/` is now in the load path.\n\n        +[lib]\n        +lib = inc\n\n# ATTRIBUTES\n\n## `lib`\n\nThis attribute can be specified 1 or more times, each time specifying\na path which will be assumed to be a path relative to `$zilla-\u003eroot`\n\nPaths specified will be passed to [`lib.pm`](https://metacpan.org/pod/lib)`-\u003eimport` in the\nsame order as they appear in your configuration, after absolutizing them.\n\n`lib.pm` prepends the values to `@INC` in a nature akin to\n\n    unshift(@INC, @{ $lib })\n\nWhich is functionally similar to:\n\n    @INC = ( @{ $lib }, @INC )\n\nThat is, retaining the specified order in ` @INC `.\n\n# RELATED READING\n\n## `dot-in-INC`\n\n- [Todd Rinaldo - How removing `\".\"` from `@INC` is about to break CPAN](http://blogs.perl.org/users/todd_rinaldo/2016/11/how-removing-from-inc-is-about-to-break-cpan.html)\n- [Todd Rinaldo - What happened to `\".\"` in `@INC`](http://blogs.perl.org/users/todd_rinaldo/2016/11/what-happened-to-dot-in-inc.html)\n\n# AUTHOR\n\nKent Fredric \u003ckentnl@cpan.org\u003e\n\n# COPYRIGHT AND LICENSE\n\nThis software is copyright (c) 2017 by Kent Fredric \u003ckentfredric@gmail.com\u003e.\n\nThis is free software; you can redistribute it and/or modify it under\nthe same terms as the Perl 5 programming language system itself.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkentnl%2Fdist-zilla-plugin-lib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkentnl%2Fdist-zilla-plugin-lib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkentnl%2Fdist-zilla-plugin-lib/lists"}