Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Missing / misleading documentation #454

Open
Unisay opened this issue Feb 11, 2023 · 2 comments
Open

Missing / misleading documentation #454

Unisay opened this issue Feb 11, 2023 · 2 comments

Comments

@Unisay
Copy link
Contributor

Unisay commented Feb 11, 2023

When user tries to compile source code files with a bare purs compiler she gets the following (expected) error:

$ purs compile -v "src/**/*.purs" -g corefn,js                                         
Error found:
in module TestPrelude
at src/TestPrelude.purs:3:1 - 3:15 (line 3, column 1 - line 3, column 15)

  Module Prelude was not found.
  Make sure the source file exists, and that it has been provided as an input to the compiler.

See https://github.com/purescript/documentation/blob/master/errors/ModuleNotFound.md for more information,
or to contribute content related to this error.

User navigates to the markdown error description mentioned in the error message and gets the following content:
image

This documentation does explain that compiler is unable to find a module from a library, but it doesn't explain how to fix the problem - how should a user tell the compiler where to find that library?

There is a mention of purs build command, that isn't there at all:

purs --help        
Usage: purs COMMAND

  The PureScript compiler and tools

Available options:
  --version                Show the version number
  -h,--help                Show this help text

Available commands:
  bundle                   This command was removed in v0.15.0. Run this command
                           for migration information.
  compile                  Compile PureScript source files
  docs                     Generate documentation from PureScript source files
                           in a variety of formats, including Markdown and HTML
  graph                    Module dependency graph
  hierarchy                Generate a GraphViz directed graph of PureScript type
                           classes
  ide                      Start or query an IDE server process
  publish                  Generates documentation packages for upload to
                           Pursuit
  repl                     Enter the interactive mode (PSCi)

For help using each individual command, run `purs COMMAND --help`. For example,
`purs compile --help` displays options specific to the `compile` command. 

purs 0.15.7 [development build; commit: UNKNOWN]

command-line help for the purs compile command doesn't contain any clue on how to specify a path to a library:

purs compile --help                         
Usage: purs compile [FILE] [-o|--output ARG] [-v|--verbose-errors] 
                    [-c|--comments] [-g|--codegen ARG] [-p|--no-prefix] 
                    [--json-errors]

  Compile PureScript source files

Available options:
  -h,--help                Show this help text
  FILE                     The input .purs file(s).
  -o,--output ARG          The output directory (default: "output")
  -v,--verbose-errors      Display verbose error messages
  -c,--comments            Include comments in the generated code
  -g,--codegen ARG         Specifies comma-separated codegen targets to include.
                           Accepted codegen targets are 'corefn', 'docs', 'js',
                           'sourcemaps'. The default target is 'js', but if this
                           option is used only the targets specified will be
                           used.
  -p,--no-prefix           Do not include comment header
  --json-errors            Print errors to stderr as JSON

Actual result:

  1. User is unable to instruct the compiler where to find a library dependency.
  2. User is frustrated as documentation mentions the command purs build that isn't available.

Desired result:

  1. User understands from the documentation that additional command line flags need to be used in order to instruct the compiler to include a library sources;
  2. Documentation doesn't include a non-existing command;
@JordanMartinez
Copy link
Contributor

I believe you pass in source globs like so:
purs compile "src/**/*.purs" ".spago/*/*/src/**/*.purs"

@Unisay
Copy link
Contributor Author

Unisay commented Feb 11, 2023

I believe you pass in source globs like so: purs compile "src/**/*.purs" ".spago/*/*/src/**/*.purs"

Right, so this explains how to make a module available for the compiler.

The only remaining issue is the documentation referencing the non-existing purs build command.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants