Deprecate configuration()

`configuration()` will not be supported in Premake6. Marking it deprecated now so everyone has a chance to phase it out. Closes #1708.

src/base/api.lua

@@ -1149,6 +1149,8 @@
 ---
 
 	function configuration(terms)
+		-- Sep 16 2021
+		premake.warnOnce("configuration", "`configuration` has been deprecated; use `filter` instead (https://premake.github.io/docs/Filters/)")
 		if terms then
 			if (type(terms) == "table" and #terms == 1 and terms[1] == "*") or (terms == "*") then
 				terms = nil

website/docs/Command-Line-Arguments.md

@@ -40,10 +40,10 @@ newoption {
 Note the commas after each key-value pair; this is required Lua syntax for a table. Once added to your script, the option will appear in the help text, and you may use the trigger as a keyword in your configuration blocks.
 
 ```lua
-configuration "with-opengl"
+filter { "options:with-opengl" }
    links { "opengldrv" }
 
-configuration "not with-opengl"
+filter { "not options:with-opengl" }
    links { "direct3ddrv" }
 ```
 
@@ -58,7 +58,8 @@ newoption {
       { "opengl",    "OpenGL" },
       { "direct3d",  "Direct3D (Windows only)" },
       { "software",  "Software Renderer" }
-   }
+   },
+   default = "opengl"
 }
 ```
 
@@ -74,30 +75,16 @@ As before, this new option will be integrated into the help text, along with a d
 Unlike the example above, you now use the _value_ as a keyword in your configuration blocks.
 
 ```lua
-configuration "opengl"
+filter { "options:gfxapi=opengl" }
    links { "opengldrv" }
 
-configuration "direct3d"
+filter { "options:gfxapi=direct3d" }
     links { "direct3ddrv" }
 
-configuration "software"
+filter { "options:gfxapi=software" }
     links { "softwaredrv" }
 ```
 
-Or you could be more clever.
-
-```lua
-links { _OPTIONS["gfxapi"] .. "drv" }
-```
-
-In this example, you would also want to provide a default behavior for the case where no option is specified. You could place a bit of code like this anywhere in your script.
-
-```lua
-if not _OPTIONS["gfxapi"] then
-   _OPTIONS["gfxapi"] = "opengl"
-end
-```
-
 As a last example of options, you may want to specify an option that accepts an unconstrained value, such as an output path. Just leave off the list of allowed values.
 
 ```lua

website/docs/buildoptions.md

@@ -23,6 +23,6 @@ Premake 4.0 or later.
 Use `pkg-config` style configuration when building on Linux with GCC. Build options are always compiler specific and should be targeted to a particular toolset.
 
 ```lua
-configuration { "linux", "gmake" }
+filter { "system:linux", "action:gmake" }
   buildoptions { "`wx-config --cxxflags`", "-ansi", "-pedantic" }
 ```

website/docs/configuration.md

@@ -4,7 +4,7 @@ Limits the subsequent build settings to a particular environment.
 configuration { "keywords" }
 ```
 
-**This function will soon be deprecated and its use is discouraged.** Use the new [filter()](filter.md) function instead; you will get more granular matching and much better performance.
+**This function has been deprecated in Premake 5.0 beta1.** Use the new [filter()](filter.md) function instead; you will get more granular matching and much better performance. `configuration()` will be not supported in Premake 6.
 
 ### Parameters ###
 

website/docs/debugargs.md

@@ -23,6 +23,6 @@ Premake 4.4 or later.
 ### Examples ###
 
 ```lua
-configuration "Debug"
+filter { "configurations:Debug" }
    debugargs { "--append", "somefile.txt" }
 ```

website/docs/debugdir.md

@@ -24,6 +24,6 @@ Premake 4.4 or later.
 ### Examples ###
 
 ```lua
-configuration "Debug"
+filter { "configurations:Debug" }
    debugdir "bin/debug"
 ```

website/docs/implibsuffix.md

@@ -20,7 +20,7 @@ Premake 4.0 or later.
 
 ```lua
 -- Add "-d" to debug versions of files
-configuration "Debug"
+filter { "configurations:Debug" }
    implibsuffix "-d"
 ```
 

website/docs/linkoptions.md

@@ -22,6 +22,6 @@ Premake 4.0 or later.
 Use `pkg-config` style configuration when building on Linux with GCC. Build options are always linker specific and should be targeted to a particular toolset.
 
 ```lua
-configuration { "linux", "gmake" }
+filter { "system:linux", "action:gmake" }
   linkoptions { "`wx-config --libs`" }
 ```

website/docs/links.md

@@ -31,13 +31,13 @@ Premake 4.0 or later.
 Link against some system libraries.
 
 ```lua
-configuration "windows"
+filter { "system:windows" }
    links { "user32", "gdi32" }
 
-configuration "linux"
+filter { "system:linux" }
    links { "m", "png" }
 
-configuration "macosx"
+filter { "system:macosx" }
    -- OS X frameworks need the extension to be handled properly
    links { "Cocoa.framework", "png" }
   ```

website/docs/postbuildcommands.md

@@ -19,10 +19,10 @@ Premake 4.4 or later.
 ### Examples ###
 
 ```lua
-configuration "windows"
+filter { "system:windows" }
    postbuildcommands { "copy default.config bin\\project.config" }
 
-configuration "not windows"
+filter { "not system:windows" }
    postbuildcommands { "cp default.config bin/project.config" }
 ```
 

website/docs/prebuildcommands.md

@@ -19,10 +19,10 @@ Premake 4.4 or later.
 ### Examples ###
 
 ```lua
-configuration "windows"
+filter { "system:windows" }
    prebuildcommands { "copy default.config bin\\project.config" }
 
-configuration "not windows"
+filter { "not system:windows" }
    prebuildcommands { "cp default.config bin/project.config" }
 ```
 

website/docs/prelinkcommands.md

@@ -19,10 +19,10 @@ Premake 4.4 or later.
 ### Examples ###
 
 ```lua
-configuration "windows"
+filter { "system:windows" }
    prelinkcommands { "copy default.config bin\\project.config" }
 
-configuration "not windows"
+filter { "not system:windows" }
    prelinkcommands { "cp default.config bin/project.config" }
 ```
 

website/docs/resoptions.md

@@ -21,6 +21,6 @@ Premake 4.0 or later.
 Use `pkg-config` style configuration when building on Linux with GCC. Build options are always compiler specific and should be targeted to a particular toolset.
 
 ```lua
-configuration { "linux", "gmake" }
+filter { "system:linux", "action:gmake" }
   resoptions { "`wx-config --cxxflags`", "-ansi", "-pedantic" }
 ```

website/docs/targetdir.md

@@ -25,10 +25,10 @@ This project separates its compiled output by configuration type.
 ```lua
 project "MyProject"
 
-  configuration "Debug"
+  filter { "configurations:Debug" }
     targetdir "bin/debug"
 
-  configuration "Release"
+  filter { "configurations:Release" }
     targetdir "bin/release"
 ```
 

website/docs/targetsuffix.md

@@ -20,7 +20,7 @@ Premake 4.0 or later.
 
 ```lua
 -- Add "-d" to debug versions of files
-configuration "Debug"
+filter { "configurations:Debug" }
    targetsuffix "-d"
 ```