diff mbox

[PATCHv2,PR,67425] Fix docs for -frandom-seed

Message ID 5682C531.60903@samsung.com
State New
Headers show

Commit Message

Yury Gribov Dec. 29, 2015, 5:38 p.m. UTC 
On 12/29/2015 08:05 PM, Sandra Loosemore wrote:
> On 12/29/2015 12:33 AM, Yury Gribov wrote:
>>
>> Hi all,
>>
>> this patch reverts invalid documentation change -frandom-seed which was
>> introduced by myself in r216773 a year ago.
>>
>> I've checked the generated man and the only test for -frandom-seed
>> (gcc.dg/pr61868.c).
>>
>> Ok for trunk?  I also want to backport to GCC5 branch.
>>
>> [snip]
>>
>> @@ -7464,7 +7464,7 @@ the first option takes effect and the subsequent
>> options are
>>  ignored. Thus only @file{vec.miss} is produced which contains
>>  dumps from the vectorizer about missed opportunities.
>>
>> -@item -frandom-seed=@var{number}
>> +@item -frandom-seed=@var{string}
>>  @opindex frandom-seed
>>  This option provides a seed that GCC uses in place of
>>  random numbers in generating certain symbol names
>
> As a user reading this documentation, I wouldn't understand what kind of
> string to use as an argument here, or how GCC actually uses it. (Usually
> a "random seed" is something that is used to generate a reproductible
> sequence of "random" numbers, not something used in place of "random"
> numbers.)  Can you do something to clarify the usage, instead of just
> renaming the parameter?

Right, thanks.  I've only added description of input argument in this 
new patch.  I'll be able to submit a detailed description of 
functionality when I'm back from holidays in 2016)

-Y

Comments

Sandra Loosemore Dec. 30, 2015, 1:47 a.m. UTC | #1 
On 12/29/2015 10:38 AM, Yury Gribov wrote:
> On 12/29/2015 08:05 PM, Sandra Loosemore wrote:
>> [snip]
>>
>> As a user reading this documentation, I wouldn't understand what kind of
>> string to use as an argument here, or how GCC actually uses it. (Usually
>> a "random seed" is something that is used to generate a reproductible
>> sequence of "random" numbers, not something used in place of "random"
>> numbers.)  Can you do something to clarify the usage, instead of just
>> renaming the parameter?
>
> Right, thanks.  I've only added description of input argument in this
> new patch.  I'll be able to submit a detailed description of
> functionality when I'm back from holidays in 2016)

Actually, I think your revised patch is fine for user documention.  It 
just needs one little grammar tweak:

> @@ -7473,7 +7473,11 @@ place unique stamps in coverage data files and the object files that
>  produce them.  You can use the @option{-frandom-seed} option to produce
>  reproducibly identical object files.
>
> -The @var{number} should be different for every file you compile.
> +The @var{string} can either be a number (decimal, octal or hex) or an
> +arbitrary string (in which case it's converted to number by

s/number/a number/

> +computing CRC32).
> +
> +The @var{string} should be different for every file you compile.
>
>  @item -fsched-verbose=@var{n}
>  @opindex fsched-verbose

OK with that change.

-Sandra
diff mbox

Patch

From 4f99bc09d1055e02df89c5fb1b4389d955ef78e5 Mon Sep 17 00:00:00 2001
From: Yury Gribov <y.gribov@samsung.com>
Date: Fri, 25 Dec 2015 13:57:28 +0300
Subject: [PATCH] Fix docs for -frandom-seed to allow string arguments.

2015-12-29  Yury Gribov  <y.gribov@samsung.com>

	PR driver/67425
	* common.opt (frandom-seed): Fix parameter name.
	* doc/invoke.texi (frandom-seed): Ditto.  Describe parameter.
---
 gcc/common.opt      |  2 +-
 gcc/doc/invoke.texi | 10 +++++++---
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/gcc/common.opt b/gcc/common.opt
index 23f394d..1f0daf0 100644
--- a/gcc/common.opt
+++ b/gcc/common.opt
@@ -1909,7 +1909,7 @@  Common Var(common_deferred_options) Defer
 
 frandom-seed=
 Common Joined RejectNegative Var(common_deferred_options) Defer
--frandom-seed=<number>	Make compile reproducible using <number>.
+-frandom-seed=<string>	Make compile reproducible using <string>.
 
 ; This switch causes the command line that was used to create an
 ; object file to be recorded into the object file.  The exact format
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 4e2cf8f..112c461 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -364,7 +364,7 @@  Objective-C and Objective-C++ Dialects}.
 -fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report -fprofile-arcs @gol
 -fopt-info @gol
 -fopt-info-@var{options}@r{[}=@var{file}@r{]} @gol
--frandom-seed=@var{number} -fsched-verbose=@var{n} @gol
+-frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
 -fsel-sched-verbose -fsel-sched-dump-cfg -fsel-sched-pipelining-verbose @gol
 -fstack-usage  -ftest-coverage  -ftime-report -fvar-tracking @gol
 -fvar-tracking-assignments  -fvar-tracking-assignments-toggle @gol
@@ -7464,7 +7464,7 @@  the first option takes effect and the subsequent options are
 ignored. Thus only @file{vec.miss} is produced which contains
 dumps from the vectorizer about missed opportunities.
 
-@item -frandom-seed=@var{number}
+@item -frandom-seed=@var{string}
 @opindex frandom-seed
 This option provides a seed that GCC uses in place of
 random numbers in generating certain symbol names
@@ -7473,7 +7473,11 @@  place unique stamps in coverage data files and the object files that
 produce them.  You can use the @option{-frandom-seed} option to produce
 reproducibly identical object files.
 
-The @var{number} should be different for every file you compile.
+The @var{string} can either be a number (decimal, octal or hex) or an
+arbitrary string (in which case it's converted to number by
+computing CRC32).
+
+The @var{string} should be different for every file you compile.
 
 @item -fsched-verbose=@var{n}
 @opindex fsched-verbose
-- 
1.9.1