diff --git a/xorriso/xorriso.1 b/xorriso/xorriso.1 index abdb9f6d..52e6a190 100644 --- a/xorriso/xorriso.1 +++ b/xorriso/xorriso.1 @@ -9,7 +9,7 @@ .\" First parameter, NAME, should be all caps .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection .\" other parameters are allowed: see man(7), man(1) -.TH XORRISO 1 "Version 1.5.7, Apr 24, 2025" +.TH XORRISO 1 "Version 1.5.7, Jun 10, 2025" .\" Please adjust this date whenever revising the manpage. .\" .\" Some roff macros, for reference: @@ -6582,6 +6582,53 @@ Use text as name of this program in subsequent messages .TP \fB\-prog_help\fR text Use text as name of this program and perform \-help. +.TP +.B Reproducibility considerations: +.PP +Stable versions of xorriso are prepared to produce in repeated runs from +the same input files with the same file metadata and the same xorriso commands +the same ISO 9660 filesystem bytes. The only exception are bytes which depend +on the current time of the xorriso run. +.br +These time dependent values can be set to fixed values by the commands +\-volume_date "uuid", \-boot_image "any" "gpt_disk_guid=", +\-volume_date "all_file_dates", and \-iso_nowtime. Instead of setting each of +them, it is possible to influence them all by the environment variable +SOURCE_DATE_EPOCH. +.br +SOURCE_DATE_EPOCH belongs to the specification of reproducible\-builds.org. +It is supposed to be either undefined or to contain a decimal number +which tells the seconds since january 1st 1970. If it contains a number, +then it is used as time value to set the default of +\-volume date "uuid", sets \-boot_image "any" "gpt_disk_guid=" to +"volume_date_uuid", \-volume_date "all_file_dates" to "set_to_mtime", +and \-iso_nowtime. +.br +Startup files and xorriso commands can override the effect of +SOURCE_DATE_EPOCH. +.PP +Different versions of xorriso may or may not produce the same result from +the same input and commands. Reproducibility may be prevented by bug fixes +or feature enhancements between versions. +.br +xorriso puts its version information into the Preparer Id field of the +ISO 9660 Primary Volume Descriptor by default. This may be desired in order +to clearly define which xorriso version has to be used for reproduction. +But it may also be undesired because a wider range of xorriso versions shall +not be excluded from an attempt of reproduction. +.br +Use command \-preparer_id with a text other than "@xorriso@" if you want to +override the default at first production time. This command may also be used +to explicitly set the preparer id as found in an ISO 9660 filesystem which +shall be reproduced by a different version of xorriso. The preparer id can be +inquired by command \-pvd_info. +.PP +If reproducibility of xorriso results is desired, then the precautions \- like +setting SOURCE_DATE_EPOCH \- should be done already with the original xorriso +run. All input files, the used xorriso commands in exact sequence, the version +of xorriso, and the possibly set SOURCE_DATE_EPOCH value should then be kept +or recorded for later re\-use. +.br .br .SH EXAMPLES .SS @@ -7156,27 +7203,7 @@ The following environment variables influence the program behavior: HOME is used to find startup files of xorriso and mkisofs. .br SOURCE_DATE_EPOCH belongs to the specs of reproducible\-builds.org. -It is supposed to be either undefined or to contain a decimal number -which tells the seconds since january 1st 1970. If it contains a number, -then it is used as time value to set the default of -\-volume date "uuid", sets \-boot_image "any" "gpt_disk_guid=" to -"volume_date_uuid", \-volume_date "all_file_dates" to "set_to_mtime", -and \-iso_nowtime to "=$SOURCE_DATE_EPOCH". -.br -Startup files and program commands can override the effect of -SOURCE_DATE_EPOCH. -.br -Be aware that by default xorriso puts its version information into the -Preparer Id field of the ISO 9660 Primary Volume Descriptor. This may be -desired in order to clearly define which xorriso version has to be used for -reproduction. But it may also be undesired because a wider range of xorriso -versions shall not be excluded from an attempt of reproduction. -.br -Use command \-preparer_id with a text other than "@xorriso@" if you want to -override the default at first production time. This command may also be used -to explicitly set the preparer id as found in an ISO 9660 filesystem which -shall be reproduced by a different version of xorriso. The id can be inquired -by command \-pvd_info. +See above paragraph "Reproducibility considerations". .br .SS .SH SEE ALSO diff --git a/xorriso/xorriso.info b/xorriso/xorriso.info index 622da73e..0fd29e67 100644 --- a/xorriso/xorriso.info +++ b/xorriso/xorriso.info @@ -595,6 +595,7 @@ inner dashes are interpreted as underscores. * Emulation:: Command compatibility emulations (cdrtools) * Scripting:: Scripting, dialog and program control features * Frontend:: Support for frontend programs via stdin and stdout +* Reproducible:: Reproducibility considerations  File: xorriso.info, Node: ArgSort, Next: AqDrive, Prev: Commands, Up: Commands @@ -5330,7 +5331,7 @@ File: xorriso.info, Node: Scripting, Next: Frontend, Prev: Emulation, Up: Co readline history.  -File: xorriso.info, Node: Frontend, Next: ExDevices, Prev: Scripting, Up: Commands +File: xorriso.info, Node: Frontend, Next: Reproducible, Prev: Scripting, Up: Commands 9.22 Support for frontend programs via stdin and stdout ======================================================= @@ -5509,6 +5510,52 @@ File: xorriso.info, Node: Frontend, Next: ExDevices, Prev: Scripting, Up: Co -prog_help text Use text as name of this program and perform -help. + +File: xorriso.info, Node: Reproducible, Next: Examples, Prev: Frontend, Up: Commands + +9.23 Reproducibility considerations +=================================== + +Stable versions of xorriso are prepared to produce in repeated runs from +the same input files with the same file metadata and the same xorriso +commands the same ISO 9660 filesystem bytes. The only exception are +bytes which depend on the current time of the xorriso run. +These time dependent values can be set to fixed values by the commands +-volume_date "uuid", -boot_image "any" "gpt_disk_guid=", -volume_date +"all_file_dates", and -iso_nowtime. Instead of setting each of them, it +is possible to influence them all by the environment variable +SOURCE_DATE_EPOCH. +SOURCE_DATE_EPOCH belongs to the specification of +reproducible-builds.org. It is supposed to be either undefined or to +contain a decimal number which tells the seconds since january 1st 1970. +If it contains a number, then it is used as time value to set the +default of -volume date "uuid", sets -boot_image "any" "gpt_disk_guid=" +to "volume_date_uuid", -volume_date "all_file_dates" to "set_to_mtime", +and -iso_nowtime. +Startup files and xorriso commands can override the effect of +SOURCE_DATE_EPOCH. + + Different versions of xorriso may or may not produce the same result +from the same input and commands. Reproducibility may be prevented by +bug fixes or feature enhancements between versions. +xorriso puts its version information into the Preparer Id field of the +ISO 9660 Primary Volume Descriptor by default. This may be desired in +order to clearly define which xorriso version has to be used for +reproduction. But it may also be undesired because a wider range of +xorriso versions shall not be excluded from an attempt of reproduction. +Use command -preparer_id with a text other than "@xorriso@" if you want +to override the default at first production time. This command may also +be used to explicitly set the preparer id as found in an ISO 9660 +filesystem which shall be reproduced by a different version of xorriso. +The preparer id can be inquired by command -pvd_info. + + If reproducibility of xorriso results is desired, then the +precautions - like setting SOURCE_DATE_EPOCH - should be done already +with the original xorriso run. All input files, the used xorriso +commands in exact sequence, the version of xorriso, and the possibly set +SOURCE_DATE_EPOCH value should then be kept or recorded for later +re-use. +  File: xorriso.info, Node: Examples, Next: Files, Prev: Commands, Up: Top @@ -6048,26 +6095,8 @@ File: xorriso.info, Node: Environ, Next: Seealso, Prev: Files, Up: Top The following environment variables influence the program behavior: HOME is used to find startup files of xorriso and mkisofs. -SOURCE_DATE_EPOCH belongs to the specs of reproducible-builds.org. It -is supposed to be either undefined or to contain a decimal number which -tells the seconds since january 1st 1970. If it contains a number, then -it is used as time value to set the default of -volume date "uuid", sets --boot_image "any" "gpt_disk_guid=" to "volume_date_uuid", -volume_date -"all_file_dates" to "set_to_mtime", and -iso_nowtime to -"=$SOURCE_DATE_EPOCH". -Startup files and program commands can override the effect of -SOURCE_DATE_EPOCH. -Be aware that by default xorriso puts its version information into the -Preparer Id field of the ISO 9660 Primary Volume Descriptor. This may -be desired in order to clearly define which xorriso version has to be -used for reproduction. But it may also be undesired because a wider -range of xorriso versions shall not be excluded from an attempt of -reproduction. -Use command -preparer_id with a text other than "@xorriso@" if you want -to override the default at first production time. This command may also -be used to explicitly set the preparer id as found in an ISO 9660 -filesystem which shall be reproduced by a different version of xorriso. -The id can be inquired by command -pvd_info. +SOURCE_DATE_EPOCH belongs to the specs of reproducible-builds.org. See +above paragraph "Reproducibility considerations".  File: xorriso.info, Node: Seealso, Next: Bugreport, Prev: Environ, Up: Top @@ -6783,51 +6812,52 @@ Node: Extras15805 Node: Processing21907 Node: Dialog25744 Node: Commands27433 -Node: ArgSort29110 -Node: AqDrive30604 -Node: Loading37784 -Node: Insert68537 -Node: SetInsert80732 -Node: Manip90968 -Node: CmdFind103464 -Node: Filter125324 -Node: Writing129946 -Node: SetWrite142440 -Node: Bootable173872 -Node: Jigdo206606 -Node: Charset211609 -Node: Exception214938 -Node: DialogCtl221127 -Node: Inquiry223729 -Node: Navigate236424 -Node: Verify248477 -Node: Restore259626 -Node: Emulation271833 -Node: Scripting283409 -Node: Frontend291664 -Node: Examples301290 -Node: ExDevices302468 -Node: ExCreate303129 -Node: ExDialog304429 -Node: ExGrowing305700 -Node: ExModifying306509 -Node: ExBootable307019 -Node: ExCharset307574 -Node: ExPseudo308470 -Node: ExCdrecord309397 -Node: ExMkisofs309717 -Node: ExGrowisofs311614 -Node: ExException312767 -Node: ExTime313225 -Node: ExIncBackup313683 -Node: ExRestore317709 -Node: ExRecovery318655 -Node: Files319227 -Node: Environ320561 -Node: Seealso322000 -Node: Bugreport322800 -Node: Legal323391 -Node: CommandIdx324403 -Node: ConceptIdx343709 +Node: ArgSort29165 +Node: AqDrive30659 +Node: Loading37839 +Node: Insert68592 +Node: SetInsert80787 +Node: Manip91023 +Node: CmdFind103519 +Node: Filter125379 +Node: Writing130001 +Node: SetWrite142495 +Node: Bootable173927 +Node: Jigdo206661 +Node: Charset211664 +Node: Exception214993 +Node: DialogCtl221182 +Node: Inquiry223784 +Node: Navigate236479 +Node: Verify248532 +Node: Restore259681 +Node: Emulation271888 +Node: Scripting283464 +Node: Frontend291719 +Node: Reproducible301348 +Node: Examples303809 +Node: ExDevices304987 +Node: ExCreate305648 +Node: ExDialog306948 +Node: ExGrowing308219 +Node: ExModifying309028 +Node: ExBootable309538 +Node: ExCharset310093 +Node: ExPseudo310989 +Node: ExCdrecord311916 +Node: ExMkisofs312236 +Node: ExGrowisofs314133 +Node: ExException315286 +Node: ExTime315744 +Node: ExIncBackup316202 +Node: ExRestore320228 +Node: ExRecovery321174 +Node: Files321746 +Node: Environ323080 +Node: Seealso323431 +Node: Bugreport324231 +Node: Legal324822 +Node: CommandIdx325834 +Node: ConceptIdx345140  End Tag Table diff --git a/xorriso/xorriso.texi b/xorriso/xorriso.texi index fdbd8ab5..59b90a02 100644 --- a/xorriso/xorriso.texi +++ b/xorriso/xorriso.texi @@ -50,7 +50,7 @@ @c man .\" First parameter, NAME, should be all caps @c man .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection @c man .\" other parameters are allowed: see man(7), man(1) -@c man .TH XORRISO 1 "Version 1.5.7, Apr 24, 2025" +@c man .TH XORRISO 1 "Version 1.5.7, Jun 10, 2025" @c man .\" Please adjust this date whenever revising the manpage. @c man .\" @c man .\" Some roff macros, for reference: @@ -844,6 +844,7 @@ inner dashes are interpreted as underscores. * Emulation:: Command compatibility emulations (cdrtools) * Scripting:: Scripting, dialog and program control features * Frontend:: Support for frontend programs via stdin and stdout +* Reproducible:: Reproducibility considerations @end menu @c man .TP @node ArgSort, AqDrive, Commands, Commands @@ -7227,7 +7228,7 @@ Do not execute the line but store it in readline history. @end table @c man .TP @c man .B Support for frontend programs via stdin and stdout: -@node Frontend, ExDevices, Scripting, Commands +@node Frontend, Reproducible, Scripting, Commands @section Support for frontend programs via stdin and stdout @table @asis @c man .TP @@ -7479,6 +7480,57 @@ Use text as name of this program in subsequent messages @cindex Program, print help text, -prog_help Use text as name of this program and perform -help. @end table +@c man .TP +@c man .B Reproducibility considerations: +@node Reproducible, Examples, Frontend, Commands +@section Reproducibility considerations +@c man .PP +Stable versions of xorriso are prepared to produce in repeated runs from +the same input files with the same file metadata and the same xorriso commands +the same ISO 9660 filesystem bytes. The only exception are bytes which depend +on the current time of the xorriso run. +@* +These time dependent values can be set to fixed values by the commands +-volume_date "uuid", -boot_image "any" "gpt_disk_guid=", +-volume_date "all_file_dates", and -iso_nowtime. Instead of setting each of +them, it is possible to influence them all by the environment variable +SOURCE_DATE_EPOCH. +@* +SOURCE_DATE_EPOCH belongs to the specification of reproducible-builds.org. +It is supposed to be either undefined or to contain a decimal number +which tells the seconds since january 1st 1970. If it contains a number, +then it is used as time value to set the default of +-volume date "uuid", sets -boot_image "any" "gpt_disk_guid=" to +"volume_date_uuid", -volume_date "all_file_dates" to "set_to_mtime", +and -iso_nowtime. +@* +Startup files and xorriso commands can override the effect of +SOURCE_DATE_EPOCH. +@c man .PP +@sp 1 +Different versions of xorriso may or may not produce the same result from +the same input and commands. Reproducibility may be prevented by bug fixes +or feature enhancements between versions. +@* +xorriso puts its version information into the Preparer Id field of the +ISO 9660 Primary Volume Descriptor by default. This may be desired in order +to clearly define which xorriso version has to be used for reproduction. +But it may also be undesired because a wider range of xorriso versions shall +not be excluded from an attempt of reproduction. +@* +Use command -preparer_id with a text other than "@@xorriso@@" if you want to +override the default at first production time. This command may also be used +to explicitly set the preparer id as found in an ISO 9660 filesystem which +shall be reproduced by a different version of xorriso. The preparer id can be +inquired by command -pvd_info. +@c man .PP +@sp 1 +If reproducibility of xorriso results is desired, then the precautions - like +setting SOURCE_DATE_EPOCH - should be done already with the original xorriso +run. All input files, the used xorriso commands in exact sequence, the version +of xorriso, and the possibly set SOURCE_DATE_EPOCH value should then be kept +or recorded for later re-use. +@* @c man .br @node Examples, Files, Commands, Top @chapter Examples @@ -8215,27 +8267,7 @@ The following environment variables influence the program behavior: HOME is used to find startup files of xorriso and mkisofs. @* SOURCE_DATE_EPOCH belongs to the specs of reproducible-builds.org. -It is supposed to be either undefined or to contain a decimal number -which tells the seconds since january 1st 1970. If it contains a number, -then it is used as time value to set the default of --volume date "uuid", sets -boot_image "any" "gpt_disk_guid=" to -"volume_date_uuid", -volume_date "all_file_dates" to "set_to_mtime", -and -iso_nowtime to "=$SOURCE_DATE_EPOCH". -@* -Startup files and program commands can override the effect of -SOURCE_DATE_EPOCH. -@* -Be aware that by default xorriso puts its version information into the -Preparer Id field of the ISO 9660 Primary Volume Descriptor. This may be -desired in order to clearly define which xorriso version has to be used for -reproduction. But it may also be undesired because a wider range of xorriso -versions shall not be excluded from an attempt of reproduction. -@* -Use command -preparer_id with a text other than "@@xorriso@@" if you want to -override the default at first production time. This command may also be used -to explicitly set the preparer id as found in an ISO 9660 filesystem which -shall be reproduced by a different version of xorriso. The id can be inquired -by command -pvd_info. +See above paragraph "Reproducibility considerations". @* @sp 1 @c man .SS diff --git a/xorriso/xorrisofs.1 b/xorriso/xorrisofs.1 index 8eb9ed04..e5b0e590 100644 --- a/xorriso/xorrisofs.1 +++ b/xorriso/xorrisofs.1 @@ -9,7 +9,7 @@ .\" First parameter, NAME, should be all caps .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection .\" other parameters are allowed: see man(7), man(1) -.TH XORRISOFS 1 "Version 1.5.7, Apr 24, 2025" +.TH XORRISOFS 1 "Version 1.5.7, Jun 10, 2025" .\" Please adjust this date whenever revising the manpage. .\" .\" Some roff macros, for reference: @@ -1835,6 +1835,54 @@ Print to standard output a text that begins with "mkisofs 2.01\-Emulation Copyright (C)" .br and to standard error the version information of xorriso. +.TP +.B Reproducibility considerations: +.PP +Stable versions of xorriso are prepared to produce in repeated runs from +the same input files with the same file metadata and the same xorrisofs options +the same ISO 9660 filesystem bytes. The only exception are bytes which depend +on the current time of the xorriso run. +.br +These time dependent values can be set to fixed values by the options +\-\-modification\-date=, \-\-gpt_disk_guid, and +\-\-set_all_file_dates. Instead of setting each of +them, it is possible to influence them all by the environment variable +SOURCE_DATE_EPOCH. +.br +SOURCE_DATE_EPOCH belongs to the specification of reproducible\-builds.org. +It is supposed to be either undefined or to contain a decimal number +which tells the seconds since january 1st 1970. If it contains a number, +then it is used as time value to set the default of +\-\-modification\-date=. \-\-gpt_disk_guid defaults +to "modification\-date". The default of \-\-set_all_file_dates +is then "set_to_mtime". Further the "now" time for ISO nodes without disk +source is set to the SOURCE_DATE_EPOCH value. +.br +Startup files and xorrisofs options can override the effect of +SOURCE_DATE_EPOCH. +.PP +Different versions of xorriso may or may not produce the same result from +the same input and options. Reproducibility may be prevented by bug fixes +or feature enhancements between versions. +.br +xorriso puts its version information into the Preparer Id field of the +ISO 9660 Primary Volume Descriptor by default. This may be desired in order +to clearly define which xorriso version has to be used for reproduction. +But it may also be undesired because a wider range of xorriso versions shall +not be excluded from an attempt of reproduction. +.br +Use option \-p with a text other than "@xorriso@" if you want to +override the default at first production time. This option may also be used +to explicitly set the preparer id as found in an ISO 9660 filesystem which +shall be reproduced by a different version of xorriso. The preparer id can be +inquired by xorriso command \-pvd_info. +.PP +If reproducibility of xorrisofs results is desired, then the precautions \- like +setting SOURCE_DATE_EPOCH \- should be done already with the original xorrisofs +run. All input files, the used xorrisofs options in exact sequence, the version +of xorriso, and the possibly set SOURCE_DATE_EPOCH value should then be kept +or recorded for later re\-use. +.br .br .SH EXAMPLES .SS @@ -2308,30 +2356,8 @@ HOME is used to find xorriso and mkisofs startup files. .br MKISOFSRC may be used to point the program to a mkisofs startup file. .br -.sp 1 SOURCE_DATE_EPOCH belongs to the specs of reproducible\-builds.org. -It is supposed to be either undefined or to contain a decimal number -which tells the seconds since january 1st 1970. If it contains a number, -then it is used as time value to set the default of -\-\-modification\-date=. -\-\-gpt_disk_guid defaults to "modification\-date". -The default of \-\-set_all_file_dates is then "set_to_mtime". -Further the "now" time for ISO nodes without disk source is then set to -the SOURCE_DATE_EPOCH value. -.br -Startup files and program options can override the effect of SOURCE_DATE_EPOCH. -.br -Be aware that by default xorriso puts its version information into the -Preparer Id field of the ISO 9660 Primary Volume Descriptor. This may be -desired in order to clearly define which xorriso version has to be used for -reproduction. But it may also be undesired because a wider range of xorriso -versions shall not be excluded from an attempt of reproduction. -.br -Use option \-p with a text other than "@xorriso@" if you want to -override the default at first production time. This option may also be used -to explicitly set the preparer id as found in an ISO 9660 filesystem which -shall be reproduced by a different version of xorriso. The id can be inquired -by the generic xorriso command \-pvd_info. +See above paragraph "Reproducibility considerations". .br .SS .SH SEE ALSO diff --git a/xorriso/xorrisofs.info b/xorriso/xorrisofs.info index 8f72313f..567f4be0 100644 --- a/xorriso/xorrisofs.info +++ b/xorriso/xorrisofs.info @@ -173,6 +173,7 @@ File: xorrisofs.info, Node: Options, Next: Examples, Prev: Xorriso, Up: Top * Charset:: Character sets * Jigdo:: Jigdo Template Extraction * Miscellaneous:: Miscellaneous options +* Reproducible:: Reproducibility considerations  File: xorrisofs.info, Node: Loading, Next: SetInsert, Prev: Options, Up: Options @@ -1530,7 +1531,7 @@ counted as part of the ISO image. -checksum_algorithm_iso.  -File: xorrisofs.info, Node: Miscellaneous, Next: ExSimple, Prev: Jigdo, Up: Options +File: xorrisofs.info, Node: Miscellaneous, Next: Reproducible, Prev: Jigdo, Up: Options 5.12 Miscellaneous options ========================== @@ -1591,6 +1592,52 @@ File: xorrisofs.info, Node: Miscellaneous, Next: ExSimple, Prev: Jigdo, Up: "mkisofs 2.01-Emulation Copyright (C)" and to standard error the version information of xorriso. + +File: xorrisofs.info, Node: Reproducible, Next: Examples, Prev: Miscellaneous, Up: Options + +5.13 Reproducibility considerations +=================================== + +Stable versions of xorriso are prepared to produce in repeated runs from +the same input files with the same file metadata and the same xorrisofs +options the same ISO 9660 filesystem bytes. The only exception are +bytes which depend on the current time of the xorriso run. +These time dependent values can be set to fixed values by the options +--modification-date=, --gpt_disk_guid, and --set_all_file_dates. +Instead of setting each of them, it is possible to influence them all by +the environment variable SOURCE_DATE_EPOCH. +SOURCE_DATE_EPOCH belongs to the specification of +reproducible-builds.org. It is supposed to be either undefined or to +contain a decimal number which tells the seconds since january 1st 1970. +If it contains a number, then it is used as time value to set the +default of --modification-date=. --gpt_disk_guid defaults to +"modification-date". The default of --set_all_file_dates is then +"set_to_mtime". Further the "now" time for ISO nodes without disk +source is set to the SOURCE_DATE_EPOCH value. +Startup files and xorrisofs options can override the effect of +SOURCE_DATE_EPOCH. + + Different versions of xorriso may or may not produce the same result +from the same input and options. Reproducibility may be prevented by +bug fixes or feature enhancements between versions. +xorriso puts its version information into the Preparer Id field of the +ISO 9660 Primary Volume Descriptor by default. This may be desired in +order to clearly define which xorriso version has to be used for +reproduction. But it may also be undesired because a wider range of +xorriso versions shall not be excluded from an attempt of reproduction. +Use option -p with a text other than "@xorriso@" if you want to override +the default at first production time. This option may also be used to +explicitly set the preparer id as found in an ISO 9660 filesystem which +shall be reproduced by a different version of xorriso. The preparer id +can be inquired by xorriso command -pvd_info. + + If reproducibility of xorrisofs results is desired, then the +precautions - like setting SOURCE_DATE_EPOCH - should be done already +with the original xorrisofs run. All input files, the used xorrisofs +options in exact sequence, the version of xorriso, and the possibly set +SOURCE_DATE_EPOCH value should then be kept or recorded for later +re-use. +  File: xorrisofs.info, Node: Examples, Next: Files, Prev: Options, Up: Top @@ -2010,28 +2057,8 @@ File: xorrisofs.info, Node: Environ, Next: Seealso, Prev: Files, Up: Top The following environment variables influence the program behavior: HOME is used to find xorriso and mkisofs startup files. MKISOFSRC may be used to point the program to a mkisofs startup file. - - SOURCE_DATE_EPOCH belongs to the specs of reproducible-builds.org. -It is supposed to be either undefined or to contain a decimal number -which tells the seconds since january 1st 1970. If it contains a -number, then it is used as time value to set the default of ---modification-date=. --gpt_disk_guid defaults to "modification-date". -The default of --set_all_file_dates is then "set_to_mtime". Further the -"now" time for ISO nodes without disk source is then set to the -SOURCE_DATE_EPOCH value. -Startup files and program options can override the effect of -SOURCE_DATE_EPOCH. -Be aware that by default xorriso puts its version information into the -Preparer Id field of the ISO 9660 Primary Volume Descriptor. This may -be desired in order to clearly define which xorriso version has to be -used for reproduction. But it may also be undesired because a wider -range of xorriso versions shall not be excluded from an attempt of -reproduction. -Use option -p with a text other than "@xorriso@" if you want to override -the default at first production time. This option may also be used to -explicitly set the preparer id as found in an ISO 9660 filesystem which -shall be reproduced by a different version of xorriso. The id can be -inquired by the generic xorriso command -pvd_info. +SOURCE_DATE_EPOCH belongs to the specs of reproducible-builds.org. See +above paragraph "Reproducibility considerations".  File: xorrisofs.info, Node: Seealso, Next: Bugreport, Prev: Environ, Up: Top @@ -2617,32 +2644,33 @@ Node: Standards1573 Node: Insert3878 Node: Xorriso5724 Node: Options6870 -Node: Loading7597 -Node: SetInsert9638 -Node: SetProduct15573 -Node: SetCompl21145 -Node: SetExtras23818 -Node: SetHide36210 -Node: ImageId38209 -Node: Bootable42491 -Node: SystemArea48924 -Node: Charset70235 -Node: Jigdo71260 -Node: Miscellaneous76230 -Node: Examples78826 -Node: ExSimple79320 -Node: ExGraft79803 -Node: ExMkisofs81103 -Node: ExGrowisofs82911 -Node: ExIncBackup84101 -Node: ExIncBckAcc87277 -Node: ExBootable88982 -Node: Files93164 -Node: Environ94259 -Node: Seealso95834 -Node: Bugreport96535 -Node: Legal97128 -Node: CommandIdx98025 -Node: ConceptIdx115531 +Node: Loading7652 +Node: SetInsert9693 +Node: SetProduct15628 +Node: SetCompl21200 +Node: SetExtras23873 +Node: SetHide36265 +Node: ImageId38264 +Node: Bootable42546 +Node: SystemArea48979 +Node: Charset70290 +Node: Jigdo71315 +Node: Miscellaneous76285 +Node: Reproducible78885 +Node: Examples81391 +Node: ExSimple81885 +Node: ExGraft82368 +Node: ExMkisofs83668 +Node: ExGrowisofs85476 +Node: ExIncBackup86666 +Node: ExIncBckAcc89842 +Node: ExBootable91547 +Node: Files95729 +Node: Environ96824 +Node: Seealso97242 +Node: Bugreport97943 +Node: Legal98536 +Node: CommandIdx99433 +Node: ConceptIdx116939  End Tag Table diff --git a/xorriso/xorrisofs.texi b/xorriso/xorrisofs.texi index 071ca1e3..e8841336 100644 --- a/xorriso/xorrisofs.texi +++ b/xorriso/xorrisofs.texi @@ -50,7 +50,7 @@ @c man .\" First parameter, NAME, should be all caps @c man .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection @c man .\" other parameters are allowed: see man(7), man(1) -@c man .TH XORRISOFS 1 "Version 1.5.7, Apr 24, 2025" +@c man .TH XORRISOFS 1 "Version 1.5.7, Jun 10, 2025" @c man .\" Please adjust this date whenever revising the manpage. @c man .\" @c man .\" Some roff macros, for reference: @@ -280,6 +280,7 @@ See EXAMPLES. * Charset:: Character sets * Jigdo:: Jigdo Template Extraction * Miscellaneous:: Miscellaneous options +* Reproducible:: Reproducibility considerations @end menu @c man .PP @c man .TP @@ -2290,7 +2291,7 @@ The rules for list_of_names are the same as with -checksum_algorithm_iso. @end table @c man .TP @c man .B Miscellaneous options: -@node Miscellaneous, ExSimple, Jigdo, Options +@node Miscellaneous, Reproducible, Jigdo, Options @section Miscellaneous options @table @asis @sp 1 @@ -2385,6 +2386,58 @@ Print to standard output a text that begins with @* and to standard error the version information of xorriso. @end table +@c man .TP +@c man .B Reproducibility considerations: +@node Reproducible, Examples, Miscellaneous, Options +@section Reproducibility considerations +@c man .PP +Stable versions of xorriso are prepared to produce in repeated runs from +the same input files with the same file metadata and the same xorrisofs options +the same ISO 9660 filesystem bytes. The only exception are bytes which depend +on the current time of the xorriso run. +@* +These time dependent values can be set to fixed values by the options +@minus{}@minus{}modification-date=, @minus{}@minus{}gpt_disk_guid, and +@minus{}@minus{}set_all_file_dates. Instead of setting each of +them, it is possible to influence them all by the environment variable +SOURCE_DATE_EPOCH. +@* +SOURCE_DATE_EPOCH belongs to the specification of reproducible-builds.org. +It is supposed to be either undefined or to contain a decimal number +which tells the seconds since january 1st 1970. If it contains a number, +then it is used as time value to set the default of +@minus{}@minus{}modification-date=. @minus{}@minus{}gpt_disk_guid defaults +to "modification-date". The default of @minus{}@minus{}set_all_file_dates +is then "set_to_mtime". Further the "now" time for ISO nodes without disk +source is set to the SOURCE_DATE_EPOCH value. +@* +Startup files and xorrisofs options can override the effect of +SOURCE_DATE_EPOCH. +@c man .PP +@sp 1 +Different versions of xorriso may or may not produce the same result from +the same input and options. Reproducibility may be prevented by bug fixes +or feature enhancements between versions. +@* +xorriso puts its version information into the Preparer Id field of the +ISO 9660 Primary Volume Descriptor by default. This may be desired in order +to clearly define which xorriso version has to be used for reproduction. +But it may also be undesired because a wider range of xorriso versions shall +not be excluded from an attempt of reproduction. +@* +Use option -p with a text other than "@@xorriso@@" if you want to +override the default at first production time. This option may also be used +to explicitly set the preparer id as found in an ISO 9660 filesystem which +shall be reproduced by a different version of xorriso. The preparer id can be +inquired by xorriso command -pvd_info. +@c man .PP +@sp 1 +If reproducibility of xorrisofs results is desired, then the precautions - like +setting SOURCE_DATE_EPOCH - should be done already with the original xorrisofs +run. All input files, the used xorrisofs options in exact sequence, the version +of xorriso, and the possibly set SOURCE_DATE_EPOCH value should then be kept +or recorded for later re-use. +@* @c man .br @node Examples, Files, Options, Top @chapter Examples @@ -2959,31 +3012,8 @@ HOME is used to find xorriso and mkisofs startup files. @* MKISOFSRC may be used to point the program to a mkisofs startup file. @* -@sp 1 -@c man .sp 1 SOURCE_DATE_EPOCH belongs to the specs of reproducible-builds.org. -It is supposed to be either undefined or to contain a decimal number -which tells the seconds since january 1st 1970. If it contains a number, -then it is used as time value to set the default of -@minus{}@minus{}modification-date=. -@minus{}@minus{}gpt_disk_guid defaults to "modification-date". -The default of @minus{}@minus{}set_all_file_dates is then "set_to_mtime". -Further the "now" time for ISO nodes without disk source is then set to -the SOURCE_DATE_EPOCH value. -@* -Startup files and program options can override the effect of SOURCE_DATE_EPOCH. -@* -Be aware that by default xorriso puts its version information into the -Preparer Id field of the ISO 9660 Primary Volume Descriptor. This may be -desired in order to clearly define which xorriso version has to be used for -reproduction. But it may also be undesired because a wider range of xorriso -versions shall not be excluded from an attempt of reproduction. -@* -Use option -p with a text other than "@@xorriso@@" if you want to -override the default at first production time. This option may also be used -to explicitly set the preparer id as found in an ISO 9660 filesystem which -shall be reproduced by a different version of xorriso. The id can be inquired -by the generic xorriso command -pvd_info. +See above paragraph "Reproducibility considerations". @* @c man .SS @c man .SH SEE ALSO