home | help 
PORTEDIT(1)		     General Commands Manual		     PORTEDIT(1)

NAME
     portedit -- edit and refactor FreeBSD Ports Collection Makefiles

SYNOPSIS
     portedit apply list
     portedit apply edit [-D[context]] [-diuU] [-w wrapcol] [Makefile]
     portedit bump-revision [-D[context]] [-diuU] [-w wrapcol] [Makefile]
     portedit bump-epoch [-D[context]] [-diuU] [-w wrapcol] [Makefile]
     portedit get variable-regexp [Makefile]
     portedit merge [-D[context]] [-diuU] [-w wrapcol] [-e expr] [Makefile]
     portedit sanitize-append [-D[context]] [-diuU] [-w wrapcol] [Makefile]
     portedit set-version [-D[context]] [-diuU] [-w wrapcol] version [Makefile]
     portedit unknown-targets [Makefile]
     portedit unknown-vars [Makefile]

DESCRIPTION
     portedit  is  a  tool  for editing and refactoring FreeBSD Ports Collection
     Makefiles.

     If the optional Makefile argument is not given, the Makefile will	be  read
     from stdin.

     The  following  options  are  shared between the bump-epoch, bump-revision,
     merge, sanitize-append, set-version commands and portfmt(1).

     -D[context]
	     Output a unified diff from the original to the  formatted	version.
	     This can optionally be followed by the number of context lines.  It
	     defaults to 3 lines of context.  For full context use 0.

     -d      Dump  the	AST  to  stdout.  This is only useful for debugging pur-
	     poses.

     -i      Format Makefile in-place instead of writing the result to stdout.

     -u      Leave variables unsorted.

     -U      Always sort variables.

     -w wrapcol
	     Sets the wrapping column to wrapcol (default: 80).  This is a  goal
	     not  a  hard  value.  It will be ignored for several variables like
	     COMMENT, DISTFILES, MASTER_SITES, etc.

	     With a value of -1 it is ignored for all variables.  Variables with
	     wrapped tokens over multiple lines will be concatenated onto a sin-
	     gle line.

COMMANDS
     portedit apply list

	 List all available edits.

     portedit apply edit [-D[context]] [-diuU] [-w wrapcol] [Makefile]

	 Run the selected edit.

     portedit bump-epoch [-D[context]] [-diuU] [-w wrapcol] [Makefile]

	 Same as bump-revision but for PORTEPOCH.

     portedit bump-revision [-D[context]] [-diuU] [-w wrapcol] [Makefile]

	 Increments PORTREVISION by one.  It will be  inserted	if  not  already
	 present in the Makefile.  If PORTREVISION is not currently in the right
	 place it will be moved as part of the operation.

     portedit get variable-regexp [Makefile]

	 Returns  the raw tokens of a variable matching the extended regular ex-
	 pression (see re_format(7)) variable-regexp.

     portedit merge [-D[context]] [-diuU] [-w wrapcol] [-e expr] [Makefile]

	 Merges files in make(1) syntax into Makefile.	The input is  read  from
	 stdin in the normal case, but one or more -e can be used to specify the
	 input instead.  Each -e is treated as if it would be an input line.

	 This  is currently limited to variables only.	Conditionals and targets
	 are ignored.

	 The != modifier is overloaded to delete variables.  += will  append  to
	 the specified variable.  No deduplication of tokens happens yet.

	 Variables in the target Makefile should be in the order as suggested by
	 portclippy(1) for best results when inserting new variables.

     portedit sanitize-append [-D[context]] [-diuU] [-w wrapcol] [Makefile]

	 Sanitize += in Makefiles before bsd.port.options.mk or bsd.port.pre.mk.
	 This  prevents  leaking  variable  values  from  the build environment.
	 CXXFLAGS, CFLAGS, LDFLAGS, RUSTFLAGS will not be sanitized since  users
	 might	want  to set optimization flags that affect port builds in their
	 environment.

     portedit set-version [-D[context]] [-diuU] [-w wrapcol] version [Makefile]

	 Sets the port version.  If the port currently has PORTVERSION	it  will
	 be  used  again for the new version.  Otherwise it defaults to DISTVER-
	 SION.

	 PORTREVISION will be removed (reset to 0).   However  special	care  is
	 taken	for  slave ports where PORTREVISION will not be removed and will
	 be set to 0 explicitly to prevent inheriting the revision from the mas-
	 ter port.

	 It tries to be smart based on the format of version.

	 If version starts with the current value of DISTVERSIONPREFIX	or  ends
	 with the current value of DISTVERSIONSUFFIX, it will be trimmed accord-
	 ingly to set DISTVERSION or PORTVERSION correctly.

	 If  version  is  in  the  format  as  returned  by git describe --tags,
	 DISTVERSION{PREFIX,SUFFIX} will be set accordingly.

     portedit unknown-targets [Makefile]

	 List targets that are not known to portedit or portclippy(1).

     portedit unknown-vars [Makefile]

	 List variables that are not known to portedit or portclippy(1).

ENVIRONMENT
     The following environment variables affect the execution of portedit:

     CLICOLOR_FORCE  If defined portedit will output text with ANSI colors  even
		     when stdout is not a tty or NO_COLOR is set.

     NO_COLOR	     If defined colors will be disabled.

EXIT STATUS
     portedit will exit with one of the following values:

     0	     Success.

     1	     An error occurred.

     2	     There were changes when compared to the original file.  Only possi-
	     ble with -D.

EXAMPLES
     Append pkgconfig to USES and delete MASTER_SITES:

	   $ printf 'USES+=pkgconfig\nMASTER_SITES!=' | portedit merge -i Makefile

     Or alternatively using -e:

	   $ portedit merge -i -e 'USES+=pkgconfig' -e 'MASTER_SITES!=' Makefile

     During  maintainance of USES=cargo ports we have to regenerate CARGO_CRATES
     and related variables based on output of make cargo-crates.  We  can  merge
     the output of this command into our Makefile with portedit merge:

	   $ make cargo-crates
	   CARGO_CRATES=   # ...
	   $ make cargo-crates | portedit merge -i Makefile

     We  have  to  run	make  cargo-crates twice since the first time the output
     might not be clean and might contain framework messages.

     A port that is using a versioning scheme that is derived from git	describe
     --tags might have

	   DISTVERSIONPREFIX=	   v
	   DISTVERSION=    0.9.2-259
	   DISTVERSIONSUFFIX=	   -gc07c115

     To update it we can run

	   $ portedit set-version -i v0.9.2-279-gc23f123

     The triple will have been updated accordingly:

	   DISTVERSIONPREFIX=	   v
	   DISTVERSION=    0.9.2-279
	   DISTVERSIONSUFFIX=	   -gc23f123

SEE ALSO
     portclippy(1), portfmt(1)

AUTHORS
     Tobias Kortkamp <tobik@FreeBSD.org>

FreeBSD ports 15.quarterly     September 19, 2021		     PORTEDIT(1)
home | help