Perl - Readme Drift
Maintainers usually reply within 2 days
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 76/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- markdown
- Domain
- documentation
Research direction
Read src/CommunityToolkit.Aspire.Hosting.Perl/README.md alongside src/CommunityToolkit.Aspire.Hosting.Perl/PerlAppResourceBuilderExtensions.cs and its PackageManager partial. Start by checking the four AddPerl* entry points, their command behavior, path handling, and the run-mode dependency-file detection referenced in the issue. Update the README to describe those behaviors and verify each statement against the code; done when the README accurately documents all three points raised.
Written by the indexing model from the issue text.
Description
Page URL
Describe the issue
Describe the bug
README.md disagrees with the code:
-
Entry points. "Core Concepts" (README.md#L40)
says the integration provides two entry points (AddPerlScript,AddPerlApi). There are four:
AddPerlModuleandAddPerlExecutableare missing. -
Script path base. The "Key insight" callout
(README.md#L98) says:The script path in
AddPerlScript/AddPerlApiis relative toAppHost.csThe XML docs and the implementation resolve the script path relative to
appDirectory: it's
passed as a bare argument and the working directory isappDirectory. In the README's own
"../scripts"example the script path is"Worker.pl", which only works relative toappDirectory. -
Implicit
WithProjectDependencies(). The Package Management table and callout
(README.md#L137,
#L141-L143) already say that calling
WithProjectDependencies()switches the defaultcpantocpanm. They don't say that in run mode every
AddPerl*method callsWithProjectDependencies()itself whenappDirectorycontainscpanfile,
Makefile.PL, orBuild.PL
(PerlAppResourceBuilderExtensions.cs#L254-L259,
HasDependencyFiles).
A resource with no package-manager calls then gets acpanminstaller and acpanmrequired-command
check
(PerlAppResourceBuilderExtensions.PackageManager.cs#L275-L280,
#L34).
Users are surprised whencpanmis reported missing.Related, out of scope here: detection runs inside
AddPerl*, so a later.WithCarton()replaces the
package manager but leaves thecpanmcheck in place. If that behavior should change, file it as a
separate code issue. This issue only documents current behavior.
Suggestion
The README lists all four Add* methods and the command each one runs:
| Method | Runs |
|---|---|
AddPerlScript |
perl -s <script> |
AddPerlApi |
perl <script> daemon |
AddPerlModule |
perl -M<Module> -e "<Module>->run()" (the module must provide run and be on @INC; the integration adds only WithLocalLib paths to PERL5LIB) |
AddPerlExecutable |
<executable> directly |
The "Key insight" callout says the script path, WithLocalLib, cpanfile discovery, and the working
directory are all relative to appDirectory, which is itself relative to the AppHost project
directory.
The Package Management section documents the auto-detection: which files trigger it, that it runs only
in run mode (publish behavior is issue 09), and that it switches the default cpan to cpanm.
Add this to the existing callout at L141-L143 rather than as a new paragraph after it (see below).
The fix inserts it between L142 and L143. git merge-tree against each branch below reports a clean merge.
Additional context
No response
Help us help you
Yes, I'd like to be assigned to work on this item
- Dominant language
- C#
- Stars
- 632
- Forks
- 204
- Avg merge
- 2d 12h
- Merged PRs (30d)
- 79
Getting set up
Starts the project's dev container in your browser, under your own GitHub account.
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from CommunityToolkit/Aspire
-
Update Toolkit to Aspire 17 nightly 17.0.0-preview.1.26553.5Possibly taken @aaronpowell claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
CommunityToolkit/Aspire#2373 ·
Maintainers usually reply within 2 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
CommunityToolkit/Aspire#1622 · 6 comments ·
Maintainers usually reply within 2 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
CommunityToolkit/Aspire#1620 · 6 comments ·
Maintainers usually reply within 2 days
-
feature request :mailbox_with_mail:
Difficulty 5/5 Over a week Newbie friendliness 30/100
CommunityToolkit/Aspire#2342 · 5 comments ·
Maintainers usually reply within 2 days
-
[Floci] Service Bus host ports are probed then released, so another process can take them before the Artemis sidecar bindsPossibly taken @thomhurst claimed this 7 days ago. Open
Difficulty 4/5 3-5 days Newbie friendliness 20/100
CommunityToolkit/Aspire#2335 ·
Maintainers usually reply within 2 days
All issues in CommunityToolkit/Aspire
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
sebastienros/jint#4449 ·
Maintainers usually reply within 1 day
-
needs triage
Difficulty 2/5 1-3 hours Newbie friendliness 63/100
spectreconsole/spectre.console#2242 ·
Maintainers usually reply within 11 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
KnifeLemon/Filee#1118 ·
Maintainers usually reply within 1 day
-
[fullscreen]Openhas-image has-license has-readme new-tool ready-to-approve repo-verified
Difficulty 1/5 Under an hour Newbie friendliness 68/100
shanselman/TinyToolTown#893 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 72/100