Merge pull request #3435 from MicrosoftDocs/master637692250399017714

Repo sync for protected CLA branch

Author: Colin Robertson

docs/build/reference/nmake-function-abspath.md

@@ -0,0 +1,44 @@
+---
+description: "Learn more about: abspath NMAKE function"
+title: "abspath NMAKE function"
+ms.date: "9/30/2021"
+helpviewer_keywords: ["abspath NMAKE function", "NMAKE function, abspath"]
+monikerRange: '>=msvc-170'
+---
+# `abspath` NMAKE function
+
+Gets the absolute path for each item in a list.
+
+## Syntax
+
+```makefile
+$(abspath input)
+```
+
+### Parameters
+
+*`input`*\
+The [list](using-an-nmake-macro.md#function-list-syntax) of file paths to convert.
+
+## Return value
+
+A [list](using-an-nmake-macro.md#function-list-syntax) with each of the items from *`input`* converted to their absolute form.
+
+## Remarks
+
+`abspath` supports extended-length paths, either by using the `\\?\` prefix, or when long paths are enabled. For more information about long paths, see [Maximum Path Length Limitation](/windows/win32/fileio/maximum-file-path-limitation).
+
+## Example
+
+```makefile
+$(abspath relative\path\file.c) # If run from "c:\temp", evaluates to "c:\temp\relative\path\file.c"
+$(abspath c:\temp\..\file1.cpp c:\\temp\/dir//) # Evaluates to "c:\file1.cpp c:\temp\dir\". Follows path traversals and normalizes directory separators.
+
+# abspath can be combined with filter to find which items exist within a directory tree
+TEMP_SOURCES=$(filteri c:\temp\\%,$(abspath $(SOURCES)))
+```
+
+## See also
+
+[Macros and NMAKE](macros-and-nmake.md)\
+[NMAKE functions by category](using-an-nmake-macro.md#functions-by-category)

docs/build/reference/nmake-function-basename.md

@@ -0,0 +1,44 @@
+---
+description: "Learn more about: basename NMAKE function"
+title: "basename NMAKE function"
+ms.date: "9/30/2021"
+helpviewer_keywords: ["basename NMAKE function", "NMAKE function, basename"]
+monikerRange: '>=msvc-170'
+---
+# `basename` NMAKE function
+
+Gets the base name for each item in a list.
+
+## Syntax
+
+```makefile
+$(basename input)
+```
+
+### Parameters
+
+*`input`*\
+The [list](using-an-nmake-macro.md#function-list-syntax) of file paths to convert.
+
+## Return value
+
+A [list](using-an-nmake-macro.md#function-list-syntax) with each of the items from *`input`* converted to their base name (that is, with their extensions removed).
+
+## Remarks
+
+`basename` doesn't have any maximum path limitations.
+
+The `basename` function is equivalent to using the [`R` modifier in a filename macro](special-nmake-macros.md#filename-macros).
+
+## Example
+
+```makefile
+$(basename c:\temp\file.txt) # Evaluates to "c:\temp\file"
+$(basename c:\temp\ c:\file) # Evaluates to "c:\temp\ c:\file" - Directories and files without extensions are left as-is
+$(basename c:\src\.gitignore) # Evaluates to "c:\src\" - Dot files are considered to be extensions and so are removed
+```
+
+## See also
+
+[Macros and NMAKE](macros-and-nmake.md)\
+[NMAKE functions by category](using-an-nmake-macro.md#functions-by-category)

docs/build/reference/nmake-function-filter.md

@@ -0,0 +1,54 @@
+---
+description: "Learn more about: filter, filteri NMAKE functions"
+title: "filter, filteri NMAKE functions"
+ms.date: "9/30/2021"
+helpviewer_keywords: ["filter NMAKE function", "filteri NMAKE function", "NMAKE function, filter", "NMAKE function, filteri"]
+monikerRange: '>=msvc-170'
+---
+# `filter`, `filteri` NMAKE functions
+
+Evaluates to a list of items that matched at least one pattern.
+
+## Syntax
+
+```makefile
+$(filter filters,input)
+$(filteri filters,input)
+```
+
+### Parameters
+
+*`filters`*\
+A [list](using-an-nmake-macro.md#function-list-syntax) of one or more [patterns](using-an-nmake-macro.md#function-pattern-syntax) to filter by.
+
+*`input`*\
+The [list](using-an-nmake-macro.md#function-list-syntax) to be filtered.
+
+## Return value
+
+A list of all of the items in *`input`* that match at least one pattern in *`filters`*.
+
+## Remarks
+
+`filteri` is the case-insensitive version of `filter`.
+
+## Example
+
+```makefile
+$(filter He%,Hello Hey Hi) # Evaluates to "Hello Hey" - "Hi" doesn't match the filter
+$(filter %y %i,Hello Hey Hi) # Evaluates to "Hey Hi" - items are kept if they match any filter, "Hello" is dropped as it doesn't match any
+$(filter Not%Found,Hello Hey Hi) # Evaluates to "" - none of the items match any filters
+
+$(filter he%,Hello Hey Hi) # Evaluates to "" - filter is case-sensitive
+$(filteri he%,Hello Hey Hi) # Evaluates to "Hello Hey" - filteri is case-insensitive
+
+# filteri is commonly used to filter a list of files by their extensions
+CPP_SOURCES=$(filteri %.cpp %.cxx,$(SOURCES))
+C_SOURCES=$(filteri %.c,$(SOURCES))
+```
+
+## See also
+
+[Macros and NMAKE](macros-and-nmake.md)\
+[NMAKE functions by category](using-an-nmake-macro.md#functions-by-category)\
+[`filterout`, `filterouti`](nmake-function-filterout.md)

docs/build/reference/nmake-function-filterout.md

@@ -0,0 +1,50 @@
+---
+description: "Learn more about: filterout, filterouti NMAKE functions"
+title: "filterout, filterouti NMAKE functions"
+ms.date: "9/30/2021"
+helpviewer_keywords: ["filterout NMAKE function", "filterouti NMAKE function", "NMAKE function, filterout", "NMAKE function, filterouti"]
+monikerRange: '>=msvc-170'
+---
+# `filterout`, `filterouti` NMAKE functions
+
+Evaluates to a list of items that don't match any patterns.
+
+## Syntax
+
+```makefile
+$(filterout filters,input)
+$(filterouti filters,input)
+```
+
+### Parameters
+
+*`filters`*\
+A [list](using-an-nmake-macro.md#function-list-syntax) of one or more [patterns](using-an-nmake-macro.md#function-pattern-syntax) to filter by.
+
+*`input`*\
+The [list](using-an-nmake-macro.md#function-list-syntax) to be filtered.
+
+## Return value
+
+A [list](using-an-nmake-macro.md#function-list-syntax) of all of the items in *`input`* that don't match any patterns in *`filters`*.
+
+## Remarks
+
+`filterouti` is the case-insensitive version of `filterout`.
+
+## Example
+
+```makefile
+$(filterout He%,Hello Hey Hi) # Evaluates to "Hi" - "Hello" and "Hey" match the filter
+$(filterout %y %i,Hello Hey Hi) # Evaluates to "Hello" - items are kept if they don't match any filters, "Hey" and "Hi" each match one filter
+$(filterout H%,Hello Hey Hi) # Evaluates to "" - each of the items matched the filter
+
+$(filterout he%,Hello Hey Hi) # Evaluates to "Hello Hey Hi" - filterout is case-sensitive
+$(filterouti he%,Hello Hey Hi) # Evaluates to "Hi" - filterouti is case-insensitive
+```
+
+## See also
+
+[Macros and NMAKE](macros-and-nmake.md)\
+[NMAKE functions by category](using-an-nmake-macro.md#functions-by-category)\
+[`filter`, `filteri`](nmake-function-filter.md)

docs/build/reference/nmake-function-findstring.md

@@ -0,0 +1,48 @@
+---
+description: "Learn more about: findstring, findstringi NMAKE functions"
+title: "findstring, findstringi NMAKE functions"
+ms.date: "9/30/2021"
+helpviewer_keywords: ["findstring NMAKE function", "findstringi NMAKE function", "NMAKE function, findstring", "NMAKE function, findstringi"]
+monikerRange: '>=msvc-170'
+---
+# `findstring`, `findstringi` NMAKE functions
+
+Evaluates to the searched-for string if it's found within another string.
+
+## Syntax
+
+```makefile
+$(findstring searchFor,input)
+$(findstringi searchFor,input)
+```
+
+### Parameters
+
+*`searchFor`*\
+The string to search for.
+
+*`input`*\
+The string to search in.
+
+## Return value
+
+If *`searchFor`* is found within *`input`*, then the function returns *`searchFor`*, otherwise it returns null.
+
+## Remarks
+
+`findstringi` is the case-insensitive version of `findstring`.
+
+## Example
+
+```makefile
+$(findstring Hello,Hello World!) # Evaluates to "Hello"
+$(findstring Hey,Hello World!) # Evaluates to ""
+
+$(findstring hello,Hello World!) # Evaluates to "" - findstring is case-sensitive
+$(findstringi hello,Hello World!) # Evaluates to "hello" - findstringi is case-insensitive
+```
+
+## See also
+
+[Macros and NMAKE](macros-and-nmake.md)\
+[NMAKE functions by category](using-an-nmake-macro.md#functions-by-category)

docs/build/reference/nmake-function-patsubst.md

@@ -0,0 +1,59 @@
+---
+description: "Learn more about: patsubst, patsubsti NMAKE functions"
+title: "patsubst, patsubsti NMAKE functions"
+ms.date: "9/30/2021"
+helpviewer_keywords: ["patsubst NMAKE function", "patsubsti NMAKE function", "NMAKE function, patsubst", "NMAKE function, patsubsti"]
+monikerRange: '>=msvc-170'
+---
+# `patsubst`, `patsubsti` NMAKE functions
+
+Evaluates to a list of items with each item that matches a pattern replaced by a substitution, and items that don't match kept as-is.
+
+## Syntax
+
+```makefile
+$(patsubst pattern,replacement,input)
+$(patsubsti pattern,replacement,input)
+```
+
+### Parameters
+
+*`pattern`*\
+The [pattern](using-an-nmake-macro.md#function-pattern-syntax) to search for.
+
+*`replacement`*\
+The [pattern](using-an-nmake-macro.md#function-pattern-syntax) to replace *`pattern`* with. If a wildcard is present in *`replacement`*, then it will be replaced with the text that the wildcard in *`pattern`* matched.
+
+*`input`*\
+The [list](using-an-nmake-macro.md#function-list-syntax) of items to be replaced or kept.
+
+## Return value
+
+Returns *`input`*, but each item that matches *`pattern`* is replaced by *`replacement`*. Items that don't match *`pattern`* are kept as-is.
+
+## Remarks
+
+`patsubsti` is the case-insensitive version of `patsubst`.
+
+## Example
+
+```makefile
+$(patsubst He%,_%_,Hello Hey Hi) # Evaluates to "_llo_ _y_ Hi"
+# "He" matches "Hello" and "Hey", and so "llo" and "y" are matched by the wildcard
+# and used to substitute the wildcard in the replacement. "Hi" is not matched and so is kept as-is
+
+$(patsubst Hi,Bye,Hello Hey Hi) # Evaluates to "Hello Hey Bye" - No wildcard is required
+$(patsubst %lo,Bye,Hello Hey Hi) # Evaluates to "Bye Hey Hi"
+# A wildcard can be used in the pattern without a wildcard in the replacement
+
+$(patsubst he%,_%_,Hello Hey Hi) # Evaluates to "Hello Hey Hi" - patsubst is case-sensitive, so no substitutions performed
+$(patsubst he%,_%_,Hello Hey Hi) # Evaluates to "_llo_ _y_ Hi" - patsubsti is case-insensitive
+
+# patsubsti is commonly used to change the file extensions of a list of files
+OBJ_FILES=$(patsubst %.c,%.obj,$(C_SOURCES)) $(patsubst %.cpp,%.obj,$(patsubst %.cxx,%.obj,$(CPP_SOURCES)))
+```
+
+## See also
+
+[Macros and NMAKE](macros-and-nmake.md)\
+[NMAKE functions by category](using-an-nmake-macro.md#functions-by-category)

docs/build/reference/nmake-function-strip.md

@@ -0,0 +1,44 @@
+---
+description: "Learn more about: strip NMAKE function"
+title: "strip NMAKE function"
+ms.date: "9/30/2021"
+helpviewer_keywords: ["strip NMAKE function", "NMAKE function, strip"]
+monikerRange: '>=msvc-170'
+---
+# `strip` NMAKE function
+
+Cleans up whitespace in and around a list of items.
+
+## Syntax
+
+```makefile
+$(strip input)
+```
+
+### Parameters
+
+*`input`*\
+The [list](using-an-nmake-macro.md#function-list-syntax) to be cleaned.
+
+## Return value
+
+A [list](using-an-nmake-macro.md#function-list-syntax) of the exact same items as *`input`*.
+
+## Remarks
+
+NMAKE outputs a [list](using-an-nmake-macro.md#function-list-syntax) that has a single space between each item and no leading or trailing whitespace. `strip` doesn't change any item within a list, but it does ensure that the returned list is in this canonical form. The canonical form can be useful for later operations that operate on strings instead of lists.
+
+## Example
+
+```makefile
+$(strip a   b   c d    ) # Evaluates to "a b c d"
+
+# strip is useful to get a canonical form of a list, which can then be transformed into a different format
+SINGLESPACE=$(subst ',,' ') # Use "subst" since a normal assignment trims trailing whitespace.
+INCLUDE_PATH=$(subst $(SINGLESPACE),;,$(strip $(INCLUDES)))
+```
+
+## See also
+
+[Macros and NMAKE](macros-and-nmake.md)\
+[NMAKE functions by category](using-an-nmake-macro.md#functions-by-category)