ocaml / ocaml/dune

Usability/Documentation issues with copy_files/glob

Open
#5,992 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
OCaml
Stars
1.9k
Forks
500
Avg merge
15h 21m
Merged PRs (30d)
277

Description

Expected Behavior

  1. copy_files does not warn if the <glob> expression matches a directory instead of a file. It would be very useful to report such errors, in the same way as the Cannot copy files onto themselves message already does for files in the local directory.
    Currently, if the user mistakenly uses a directory name (or even the name of a non-existing file), dune silently does nothing, without reporting any errors.

  2. It is unclear to me why (copy_files (glob_files_rec <glob>)) does not work. The copy_files documentation mentions:

    <glob> represents the set of files to copy. See the glob for details.

    That page, in turn, mentions:

    Dune supports globbing files in a single directory via (glob_files ...) and, starting with Dune 3.0, in all sub-directories recursively via (glob_files_rec ...).

    I then assumed that <glob> in the copy_files part could be replaced with (glob_files ...). So I tried using (copy_files (files (glob_files_rec ../dir/*))), but it complains with Error: Unexpected list. If I remove the files part, since the copy_files doc mentions that The short form (copy_files <glob>) is equivalent to (copy_files (files <glob>)), it then complains with Error: field files missing.
    In both cases, I am unable to combine copy_files with glob_files, which seems it should be possible from the documentation. The lack of usage examples for this option makes it harder to understand how it must be written.

Actual Behavior

  1. No errors reported in case of non-existing/directory name
  2. Error when trying to combine copy_files and glob_files; lack of usage examples.

Reproduction

First issue:

  1. cd /tmp && dune init project proj
  2. cd proj
  3. mkdir d; touch c
  4. echo "(copy_files ../d)" >> bin/dune # user meant "../c" instead of "../d"
  5. echo "(copy_files ../invalid)" >> bin/dune # user entered a non-existing path
  6. dune build

No error/warning is emitted; no files are copied.

Second issue:

  1. echo "(copy_files (glob_files_rec ../d/*))" >> bin/dune # documentation suggests it might work
  2. dune build # error
  3. Erase erroneous line from bin/dune
  4. echo "(copy_files (files (glob_files_rec ../d/*)))" >> bin/dune # documentation suggests it might work
  5. dune build # another error

Also, there are no examples with glob_files_rec.

Specifications

  • Version of dune (output of dune --version): 3.3.1
  • Version of ocaml (output of ocamlc --version): 4.08.1
  • Operating system (distribution and version): Linux Fedora 36

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the two cases in bin/dune with copy_files, glob_files, and glob_files_rec, then read the copy_files and glob documentation linked in the report. Confirm the intended behavior for directory or missing matches and the valid syntax for recursive globs. Done means the behavior is clearly diagnosed or reported, and the documentation includes accurate usage examples.

Written by the indexing model from the issue text.

Assessment

Tech stack
ocaml
Domain
build-system, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.