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

Synchronize option help in --help and man page #6955

Closed
vicuna opened this issue Aug 9, 2015 · 28 comments
Closed

Synchronize option help in --help and man page #6955

vicuna opened this issue Aug 9, 2015 · 28 comments

Comments

@vicuna
Copy link

vicuna commented Aug 9, 2015

Original bug ID: 6955
Reporter: @gasche
Status: acknowledged (set by @gasche on 2015-08-09T10:06:59Z)
Resolution: open
Priority: normal
Severity: text
Version: 4.03.0+dev / +beta1
Target version: 4.07.0+dev/beta2/rc1/rc2
Category: documentation
Tags: junior_job

Bug description

Some options are mentioned in --help but missing from the manpages, or not handled by OCAMLPARAM.

Additional information

It would be helpful to check the list of OCAMLPARAM-supported options to see if we have forgotten something else.

@vicuna
Copy link
Author

vicuna commented Apr 14, 2016

Comment author: @gasche

Here is the command I used to get the list of options listed in the manual (from the man/ directory of the source repository):

cat ocamlc.m \
 | grep -E "^\\.TP" -A 1\
 | grep ".B"\
 | sed 's/\\\\//g'\
 | grep -o -E " \\-[-_a-zA-Z][-_a-zA-Z0-9]+"\
 | sort -u

Here is the one to get the list of options listed in --help:

ocamlc --help\
 | grep -o -E " \\-[-_a-zA-Z][-_a-zA-Z0-9]+"\
 | sort -u

At the time of writing,
the list of options mentioned in the manual but not in --help is the following:
-color

the list of options mentioned in --help but not in the manual is the following:
-absname
-dinstr
-dlambda
-dparsetree
-drawlambda
-dsource
-dtimings
-dtypedtree
-dtypes
-intf_suffix
-make_runtime
-modern
-no-check-prims
-nopervasives
-opaque
-output-complete-obj
-strict-formats
-use-prims
-use_runtime
--version

@vicuna
Copy link
Author

vicuna commented Apr 14, 2016

Comment author: @gasche

This was ocamlc only. The situation is even worse for ocamlopt, with the following things missing from the manual:
-clambda-checks
-color
-dalloc
-dclambda
-dcmm
-dcombine
-dcse
-dflambda
-dflambda-let
-dflambda-no-invariants
-dflambda-verbose
-dinterf
-dlambda
-dlinear
-dlive
-dparsetree
-dprefer
-drawclambda
-drawflambda
-drawlambda
-dreload
-dscheduling
-dsel
-dsource
-dspill
-dsplit
-dstartup
-dtimings
-dtypedtree
-dtypes
-dump-pass
-inline-alloc-cost
-inline-branch-cost
-inline-branch-factor
-inline-call-cost
-inline-indirect-cost
-inline-lifting-benefit
-inline-max-depth
-inline-max-unroll
-inline-prim-cost
-inline-toplevel
-inlining-report
-keep-docs
-no-float-const-prop
-nopervasives
-no-unbox-free-vars-of-closures
-no-unbox-specialised-args
-O2
-O3
-Oclassic
-opaque
-output-complete-obj
-remove-unused-arguments
-rounds
-strict-formats
-unbox-closures
-unbox-closures-factor
--version

In the other direction, "ocamlopt -help" does not list versions not available on my architecture, so I see a list of arm-specific options:

-farch
-ffast-math
-ffpu
-fno-thumb
-fthumb
-march

@muskangarg21
Copy link
Contributor

@Octachron @gasche
May I work on this next ?

@Octachron
Copy link
Member

You certainly can, I would advise you to select a small thematic subset, for instance the flambda global optimisation-O* flags. Or everything except the flambda-specific flags. And then it would be fine to submit one PR by subset.

@muskangarg21
Copy link
Contributor

@Octachron
I am working with ocamlc.m and main_args.ml for now, so basically if there is an entry in main_args.ml we want that in ocamlc.m with that same description string, am I correct ?

@Octachron
Copy link
Member

Only if the argument is used by ocamlc, in otherwords if it appears in Main_args.Make_bytecomp_option(_).list. Note that the man page documentation can be more exhaustive than the -help text. However, as at first step, it is simpler to keep the new man entries synchronized with the main_args description..

@muskangarg21
Copy link
Contributor

So the options that are seen by running ocamlc --help should be added to the ocamlc.m if not already present. e.g. -
the option -alert is in the --help but not in manpage. so I should add the description to ocaml.c by using this:

let mk_alert f =
  "-alert", Arg.String f,
  Printf.sprintf
    "  Enable or disable alerts according to :\n\
    \        +  enable alert \n\
    \        -  disable alert \n\
    \        ++ treat  as fatal error\n\
    \        -- treat  as non-fatal\n\
    \        @  enable  and treat it as fatal error\n\
    \     can be 'all' to refer to all alert names";;

@github-actions
Copy link

This issue has been open one year with no activity. Consequently, it is being marked with the "stale" label. What this means is that the issue will be automatically closed in 30 days unless more comments are added or the "stale" label is removed. Comments that provide new information on the issue are especially welcome: is it still reproducible? did it appear in other contexts? how critical is it? etc.

@github-actions
Copy link

github-actions bot commented Jul 4, 2022

This issue has been open one year with no activity. Consequently, it is being marked with the "stale" label. What this means is that the issue will be automatically closed in 30 days unless more comments are added or the "stale" label is removed. Comments that provide new information on the issue are especially welcome: is it still reproducible? did it appear in other contexts? how critical is it? etc.

@github-actions github-actions bot added the Stale label Jul 4, 2022
@Octachron Octachron removed the Stale label Jul 4, 2022
@nangahamandine
Copy link
Contributor

Hello, I'd like to work on this issue. Can you please brief me on how to go about it? I don't clearly understand what we're required to do

@Octachron
Copy link
Member

There are two ways to get a list of flags for ocamlc and ocamlopt. One may either use the -help flag of the corresponding executable

$ ocamlopt -help

or one may read the man entry with

$ man ocamlopt

The two locations are currently slightly desynchronized. In particular, the man page entry for ocamlopt (man/ocamlopt.1) doesn't cover the flambda options. A good objective for a PR would be to focus on the flambda options described at https://v2.ocaml.org/manual/flambda.html#s:flambda-cli and add them to the man file.

@nangahamandine
Copy link
Contributor

nangahamandine commented Oct 12, 2022

Thank you for the guide, I'm a complete beginner in OCaml and contributing to open source in general so I find some difficulties navigating around everything. I'll try that and get back to you if I have any questions

@nangahamandine
Copy link
Contributor

Hello, I have been trying to to run the 'man ocamlopt' command but I get an error saying "bash: man: command not found". I'm presently in the man folder but no success. The 'ocamlopt -help' command runs just fine. How do I resolve this please?

@nangahamandine
Copy link
Contributor

Also, I'd like to clearly understand this. The flambda options described at https://v2.ocaml.org/manual/flambda.html#s:flambda-cli are required to be added to the ocamlopt.1 file in the man folder right? If so, how do I go about it please? If not, can you please enlighten me?

@Octachron
Copy link
Member

You need to install the man executable.
Yes, the option should be added to ocamlopt.1 in a Options for Flambda section. You can look at the section Options for the AMD64 architecture as an inspiration.

@nangahamandine
Copy link
Contributor

Thank you

From the flambda options described in the documentation above, do I add the Commonly-used options, Less commonly-used options and Advanced options, only needed for detailed tuning? Or just the commonly used options?

@Octachron
Copy link
Member

The commonly-used options are probably a good scope for a first PR.

@nangahamandine
Copy link
Contributor

Okay thanks

@nangahamandine
Copy link
Contributor

I'd like to continue working on this issue. Can you please suggest another subset for me to work on?

@Octachron
Copy link
Member

There are few missing negative command lines,

  • -no-principal
  • -no-rectypes
  • -no-strict-sequence
    that are missing in both ocamlc.1 and ocamlopt.1.
    Those negative options should be documented just after the options that they negate.

Similarly, the option -strict-format and -no-strict-format are missing from the manpages and could be documented.

@nangahamandine
Copy link
Contributor

I do not clearly understand how to document these missing negative command lines. If you could please elaborate more, I'd be grateful

@Octachron
Copy link
Member

You can start from the argument description provided by the command line:

  -no-principal  Do not check principality of type inference (default)
  -no-rectypes  Do not allow arbitrary recursive types (default)
  -no-strict-sequence  Left-hand part of a sequence need not have type unit (default)

@nangahamandine
Copy link
Contributor

I've noticed that the ocaml.1 file is missing these options too. Should I add them in it?

@Octachron
Copy link
Member

You are right, you can also add those options to the ocaml.1 manpage.

@nangahamandine
Copy link
Contributor

This too is missing in the ocaml.1 manpage
-runtime-variant \ suffix
Was that intentional?

@Octachron
Copy link
Member

Yes, this is intentional: the -runtime-variant flag is not a valid option for the ocaml REPL.

@nangahamandine
Copy link
Contributor

Noted

@gasche
Copy link
Member

gasche commented Oct 5, 2023

I understand that this issue was closed by merging #11647. Thanks again!

@gasche gasche closed this as completed Oct 5, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

5 participants