Move `build_config.rb` -> `build_config/default.rb`; ref #5098

In addition, update the documents referring `build_config.rb` which is
no longer used. The new `build_config.rb` describes the new configuration
structure in the comment.

16 files changed, 141 insertions, 128 deletions

diff --git a/build_config.rb b/build_config.rb
index 0a92b9108..625661df0 100644
--- a/build_config.rb
+++ b/build_config.rb
@@ -1,86 +1,9 @@
-MRuby::Build.new do |conf|
-  # load specific toolchain settings
-
-  # Gets set by the VS command prompts.
-  if ENV['VisualStudioVersion'] || ENV['VSINSTALLDIR']
-    toolchain :visualcpp
-  else
-    toolchain :gcc
-  end
-
-  # Use mrbgems
-  # conf.gem 'examples/mrbgems/ruby_extension_example'
-  # conf.gem 'examples/mrbgems/c_extension_example' do |g|
-  #   g.cc.flags << '-g' # append cflags in this gem
-  # end
-  # conf.gem 'examples/mrbgems/c_and_ruby_extension_example'
-  # conf.gem :core => 'mruby-eval'
-  # conf.gem :mgem => 'mruby-onig-regexp'
-  # conf.gem :github => 'mattn/mruby-onig-regexp'
-  # conf.gem :git => '[email protected]:mattn/mruby-onig-regexp.git', :branch => 'master', :options => '-v'
-
-  # include the GEM box
-  conf.gembox 'full-core'
-
-  # C compiler settings
-  # conf.cc do |cc|
-  #   cc.command = ENV['CC'] || 'gcc'
-  #   cc.flags = [ENV['CFLAGS'] || %w()]
-  #   cc.include_paths = ["#{root}/include"]
-  #   cc.defines = %w()
-  #   cc.option_include_path = %q[-I"%s"]
-  #   cc.option_define = '-D%s'
-  #   cc.compile_options = %Q[%{flags} -MMD -o "%{outfile}" -c "%{infile}"]
-  # end
-
-  # mrbc settings
-  # conf.mrbc do |mrbc|
-  #   mrbc.compile_options = "-g -B%{funcname} -o-" # The -g option is required for line numbers
-  # end
-
-  # Linker settings
-  # conf.linker do |linker|
-  #   linker.command = ENV['LD'] || 'gcc'
-  #   linker.flags = [ENV['LDFLAGS'] || []]
-  #   linker.flags_before_libraries = []
-  #   linker.libraries = %w()
-  #   linker.flags_after_libraries = []
-  #   linker.library_paths = []
-  #   linker.option_library = '-l%s'
-  #   linker.option_library_path = '-L%s'
-  #   linker.link_options = "%{flags} -o "%{outfile}" %{objs} %{libs}"
-  # end
-
-  # Archiver settings
-  # conf.archiver do |archiver|
-  #   archiver.command = ENV['AR'] || 'ar'
-  #   archiver.archive_options = 'rs "%{outfile}" %{objs}'
-  # end
-
-  # Parser generator settings
-  # conf.yacc do |yacc|
-  #   yacc.command = ENV['YACC'] || 'bison'
-  #   yacc.compile_options = %q[-o "%{outfile}" "%{infile}"]
-  # end
-
-  # gperf settings
-  # conf.gperf do |gperf|
-  #   gperf.command = 'gperf'
-  #   gperf.compile_options = %q[-L ANSI-C -C -p -j1 -i 1 -g -o -t -N mrb_reserved_word -k"1,3,$" "%{infile}" > "%{outfile}"]
-  # end
-
-  # file extensions
-  # conf.exts do |exts|
-  #   exts.object = '.o'
-  #   exts.executable = '' # '.exe' if Windows
-  #   exts.library = '.a'
-  # end
-
-  # file separetor
-  # conf.file_separator = '/'
-
-  # Turn on `enable_debug` for better debugging
-  # conf.enable_debug
-  conf.enable_bintest
-  conf.enable_test
-end
+# The default build configuration file was moved to `build_config/default.rb`.
+#
+# Recommended way to customize the build configuration is:
+#  * copy `default.rb` (or any config file) to a new file (e.g. `myconfig.rb`)
+#  * edit `myconfig.rb`.
+#  * `rake MRUBY_CONFIG=/path/to/myconfig.rb` to compile and test.
+#  * or `rake MRUBY_CONFIG=myconfig` if your configuration file is in the `build_config` directory.
+#  * (optional) submit your configuration as a pull-request if it's useful for others
+raise "The default configuration was moved to `build_config/default.rb`"
diff --git a/build_config/default.rb b/build_config/default.rb
new file mode 100644
index 000000000..0a92b9108
--- /dev/null
+++ b/build_config/default.rb
@@ -0,0 +1,86 @@
+MRuby::Build.new do |conf|
+  # load specific toolchain settings
+
+  # Gets set by the VS command prompts.
+  if ENV['VisualStudioVersion'] || ENV['VSINSTALLDIR']
+    toolchain :visualcpp
+  else
+    toolchain :gcc
+  end
+
+  # Use mrbgems
+  # conf.gem 'examples/mrbgems/ruby_extension_example'
+  # conf.gem 'examples/mrbgems/c_extension_example' do |g|
+  #   g.cc.flags << '-g' # append cflags in this gem
+  # end
+  # conf.gem 'examples/mrbgems/c_and_ruby_extension_example'
+  # conf.gem :core => 'mruby-eval'
+  # conf.gem :mgem => 'mruby-onig-regexp'
+  # conf.gem :github => 'mattn/mruby-onig-regexp'
+  # conf.gem :git => '[email protected]:mattn/mruby-onig-regexp.git', :branch => 'master', :options => '-v'
+
+  # include the GEM box
+  conf.gembox 'full-core'
+
+  # C compiler settings
+  # conf.cc do |cc|
+  #   cc.command = ENV['CC'] || 'gcc'
+  #   cc.flags = [ENV['CFLAGS'] || %w()]
+  #   cc.include_paths = ["#{root}/include"]
+  #   cc.defines = %w()
+  #   cc.option_include_path = %q[-I"%s"]
+  #   cc.option_define = '-D%s'
+  #   cc.compile_options = %Q[%{flags} -MMD -o "%{outfile}" -c "%{infile}"]
+  # end
+
+  # mrbc settings
+  # conf.mrbc do |mrbc|
+  #   mrbc.compile_options = "-g -B%{funcname} -o-" # The -g option is required for line numbers
+  # end
+
+  # Linker settings
+  # conf.linker do |linker|
+  #   linker.command = ENV['LD'] || 'gcc'
+  #   linker.flags = [ENV['LDFLAGS'] || []]
+  #   linker.flags_before_libraries = []
+  #   linker.libraries = %w()
+  #   linker.flags_after_libraries = []
+  #   linker.library_paths = []
+  #   linker.option_library = '-l%s'
+  #   linker.option_library_path = '-L%s'
+  #   linker.link_options = "%{flags} -o "%{outfile}" %{objs} %{libs}"
+  # end
+
+  # Archiver settings
+  # conf.archiver do |archiver|
+  #   archiver.command = ENV['AR'] || 'ar'
+  #   archiver.archive_options = 'rs "%{outfile}" %{objs}'
+  # end
+
+  # Parser generator settings
+  # conf.yacc do |yacc|
+  #   yacc.command = ENV['YACC'] || 'bison'
+  #   yacc.compile_options = %q[-o "%{outfile}" "%{infile}"]
+  # end
+
+  # gperf settings
+  # conf.gperf do |gperf|
+  #   gperf.command = 'gperf'
+  #   gperf.compile_options = %q[-L ANSI-C -C -p -j1 -i 1 -g -o -t -N mrb_reserved_word -k"1,3,$" "%{infile}" > "%{outfile}"]
+  # end
+
+  # file extensions
+  # conf.exts do |exts|
+  #   exts.object = '.o'
+  #   exts.executable = '' # '.exe' if Windows
+  #   exts.library = '.a'
+  # end
+
+  # file separetor
+  # conf.file_separator = '/'
+
+  # Turn on `enable_debug` for better debugging
+  # conf.enable_debug
+  conf.enable_bintest
+  conf.enable_test
+end
diff --git a/doc/guides/compile.md b/doc/guides/compile.md
index ad57970e3..ab774a633 100644
--- a/doc/guides/compile.md
+++ b/doc/guides/compile.md
@@ -24,24 +24,26 @@ Optional:
 
 ## Build
 
-Inside of the root directory of the mruby source a file exists
-called *build_config.rb*. This file contains the build configuration
-of mruby and looks like this for example:
+To compile `mruby` with the default build configuration, just invoke `rake`
+inside of the mruby source root. To generate and execute the test tools call
+`rake test`. To clean all build files call `rake clean`. To see full command
+line on build, call `rake -v`.
+
+You can specify your owne configration file by the `MRUBY_CONFIG` environment
+variable (you can use `CONFIG` for shorthand for `MRUBY_CONFIG`). If the path
+doesn't exist, *build_config/${MRUBY_CONFIG}.rb* is used. The default
+configuration is defined in the `build_config/default_config.rb` file.
+
+Those build configuration files contain the build configurationof mruby, for
+example:
+
 ```ruby
 MRuby::Build.new do |conf|
   toolchain :gcc
 end
 ```
 
-All tools necessary to compile mruby can be set or modified here. In case
-you want to maintain an additional *build_config.rb* you can define a
-customized path using the *$MRUBY_CONFIG* environment variable. If the
-path doesn't exist, *build_config/${MRUBY_CONFIG}.rb* is used.
-
-To compile just call `rake` inside of the mruby source root. To
-generate and execute the test tools call `rake test`. To clean
-all build files call `rake clean`. To see full command line on
-build, call `rake -v`.
+All tools necessary to compile mruby can be set or modified here.
 
 ## Build Configuration
 
@@ -306,11 +308,11 @@ When debugging mode is enabled
 
 ## Cross-Compilation
 
-mruby can also be cross-compiled from one platform to another. To
-achieve this the *build_config.rb* needs to contain an instance of
-`MRuby::CrossBuild`. This instance defines the compilation
-tools and flags for the target platform. An example could look
-like this:
+mruby can also be cross-compiled from one platform to another. To achieve
+cross-compilation, the build configuration needs to contain an instance of
+`MRuby::CrossBuild`. This instance defines the compilation tools and flags
+for the target platform. An example could look like this:
+
 ```ruby
 MRuby::CrossBuild.new('32bit') do |conf|
   toolchain :gcc
@@ -320,8 +322,9 @@ MRuby::CrossBuild.new('32bit') do |conf|
 end
 ```
 
-All configuration options of `MRuby::Build` can also be used
-in `MRuby::CrossBuild`.
+All configuration options of `MRuby::Build` can also be used in
+`MRuby::CrossBuild`. You can find examples under the *build_config*
+directory.
 
 ### Mrbtest in Cross-Compilation
 
diff --git a/doc/guides/mrbgems.md b/doc/guides/mrbgems.md
index ffbf17f26..4246587ce 100644
--- a/doc/guides/mrbgems.md
+++ b/doc/guides/mrbgems.md
@@ -5,16 +5,15 @@ standardised way into mruby.
 
 ## Usage
 
-By default mrbgems is currently deactivated. As soon as you add a GEM to your
-build configuration (i.e. *build_config.rb*), mrbgems will be activated and the
-extension integrated.
+You have to activate mrbgems explicitly in your build configuration.  To add
+a GEM, add the following line to your build configuration file, for example:
 
-To add a GEM into the *build_config.rb* add the following line for example:
 ```ruby
 conf.gem '/path/to/your/gem/dir'
 ```
 
 You can also use a relative path which would be relative from the mruby root:
+
 ```ruby
 conf.gem 'examples/mrbgems/ruby_extension_example'
 ```
@@ -54,9 +53,9 @@ NOTE: `:bitbucket` option supports only git. Hg is unsupported in this version.
 
 There are instances when you wish to add a collection of mrbgems into mruby at
 once, or be able to substitute mrbgems based on configuration, without having to
-add each gem to the *build_config.rb* file.  A packaged collection of mrbgems
+add each gem to your build configration file.  A packaged collection of mrbgems
 is called a GemBox.  A GemBox is a file that contains a list of mrbgems to load
-into mruby, in the same format as if you were adding them to *build_config.rb*
+into mruby, in the same format as if you were adding them to the build config
 via `config.gem`, but wrapped in an `MRuby::GemBox` object.  GemBoxes are
 loaded into mruby via `config.gembox 'boxname'`.
 
@@ -73,7 +72,7 @@ must be saved with a *.gembox* extension inside the *mrbgems* directory to to be
 picked up by mruby.
 
 To use this example GemBox, we save it as `custom.gembox` inside the *mrbgems*
-directory in mruby, and add the following to our *build_config.rb* file inside
+directory in mruby, and add the following to your build configration file inside
 the build block:
 ```ruby
 conf.gembox 'custom'
@@ -184,12 +183,12 @@ Version requirement supports following operators:
 
 When more than one version requirements is passed, the dependency must satisfy all of it.
 
-You can have default gem to use as dependency when it's not defined in *build_config.rb*.
+You can have default gem to use as dependency when it's not defined in your build configuration.
 When the last argument of `add_dependency` call is `Hash`, it will be treated as default gem information.
 Its format is same as argument of method `MRuby::Build#gem`, expect that it can't be treated as path gem location.
 
 When a special version of dependency is required,
-use `MRuby::Build#gem` in *build_config.rb* to override default gem.
+use `MRuby::Build#gem` in the build configuration to override default gem.
 
 If you have conflicting GEMs use the following method:
 * `spec.add_conflict(gem, *requirements)`
diff --git a/lib/mruby/build.rb b/lib/mruby/build.rb
index d07890621..c9a7097b5 100644
--- a/lib/mruby/build.rb
+++ b/lib/mruby/build.rb
@@ -40,9 +40,9 @@ module MRuby
     class << self
       attr_accessor :current
       def load_config
-        path = ENV['MRUBY_CONFIG']
+        path = ENV['MRUBY_CONFIG'] || ENV['CONFIG']
         if path.nil? || path.empty?
-          path = "#{MRUBY_ROOT}/build_config.rb"
+          path = "#{MRUBY_ROOT}/build_config/default.rb"
         elsif !File.file?(path) && !Pathname.new(path).absolute?
           f = "#{MRUBY_ROOT}/build_config/#{path}.rb"
           path = File.exist?(f) ? f : File.extname(path).empty? ? f : path
diff --git a/mrbgems/mruby-bin-debugger/tools/mrdb/mrdbconf.h b/mrbgems/mruby-bin-debugger/tools/mrdb/mrdbconf.h
index 080b0616b..e2c4c7200 100644
--- a/mrbgems/mruby-bin-debugger/tools/mrdb/mrdbconf.h
+++ b/mrbgems/mruby-bin-debugger/tools/mrdb/mrdbconf.h
@@ -7,11 +7,11 @@
 #define MRDBCONF_H
 
 #ifndef MRB_ENABLE_DEBUG_HOOK
-# error mruby-bin-debugger need 'MRB_ENABLE_DEBUG_HOOK' configuration in your 'build_config.rb'
+# error mruby-bin-debugger need 'MRB_ENABLE_DEBUG_HOOK' in your build configuration
 #endif
 
 #ifdef MRB_DISABLE_STDIO
-# error mruby-bin-debugger conflicts 'MRB_DISABLE_STDIO' configuration in your 'build_config.rb'
+# error mruby-bin-debugger conflicts 'MRB_DISABLE_STDIO' in your build configuration
 #endif
 
 /* configuration options: */
diff --git a/mrbgems/mruby-bin-mirb/tools/mirb/mirb.c b/mrbgems/mruby-bin-mirb/tools/mirb/mirb.c
index 93a4941f4..cb22d2ec3 100644
--- a/mrbgems/mruby-bin-mirb/tools/mirb/mirb.c
+++ b/mrbgems/mruby-bin-mirb/tools/mirb/mirb.c
@@ -9,7 +9,7 @@
 #include <mruby.h>
 
 #ifdef MRB_DISABLE_STDIO
-# error mruby-bin-mirb conflicts 'MRB_DISABLE_STDIO' configuration in your 'build_config.rb'
+# error mruby-bin-mirb conflicts 'MRB_DISABLE_STDIO' in your build configuration
 #endif
 
 #include <mruby/array.h>
diff --git a/mrbgems/mruby-bin-mrbc/tools/mrbc/mrbc.c b/mrbgems/mruby-bin-mrbc/tools/mrbc/mrbc.c
index acad28bd8..df674f556 100644
--- a/mrbgems/mruby-bin-mrbc/tools/mrbc/mrbc.c
+++ b/mrbgems/mruby-bin-mrbc/tools/mrbc/mrbc.c
@@ -1,7 +1,7 @@
 #include <mruby.h>
 
 #ifdef MRB_DISABLE_STDIO
-# error mruby-bin-mrbc conflicts 'MRB_DISABLE_STDIO' configuration in your 'build_config.rb'
+# error mruby-bin-mrbc conflicts 'MRB_DISABLE_STDIO' in your build configuration
 #endif
 
 #include <stdlib.h>
diff --git a/mrbgems/mruby-bin-mruby/tools/mruby/mruby.c b/mrbgems/mruby-bin-mruby/tools/mruby/mruby.c
index 793245875..e9bd4c326 100644
--- a/mrbgems/mruby-bin-mruby/tools/mruby/mruby.c
+++ b/mrbgems/mruby-bin-mruby/tools/mruby/mruby.c
@@ -1,7 +1,7 @@
 #include <mruby.h>
 
 #ifdef MRB_DISABLE_STDIO
-# error mruby-bin-mruby conflicts 'MRB_DISABLE_STDIO' configuration in your 'build_config.rb'
+# error mruby-bin-mruby conflicts 'MRB_DISABLE_STDIO' in your build configuration
 #endif
 
 #include <stdlib.h>
diff --git a/mrbgems/mruby-bin-strip/tools/mruby-strip/mruby-strip.c b/mrbgems/mruby-bin-strip/tools/mruby-strip/mruby-strip.c
index 3d05238d2..4eabb17bf 100644
--- a/mrbgems/mruby-bin-strip/tools/mruby-strip/mruby-strip.c
+++ b/mrbgems/mruby-bin-strip/tools/mruby-strip/mruby-strip.c
@@ -1,7 +1,7 @@
 #include <mruby.h>
 
 #ifdef MRB_DISABLE_STDIO
-# error mruby-bin-strip conflicts 'MRB_DISABLE_STDIO' configuration in your 'build_config.rb'
+# error mruby-bin-strip conflicts 'MRB_DISABLE_STDIO' in your build configuration
 #endif
 
 #include <stdlib.h>
diff --git a/mrbgems/mruby-io/README.md b/mrbgems/mruby-io/README.md
index 2c5b762d8..9fb942e3a 100644
--- a/mrbgems/mruby-io/README.md
+++ b/mrbgems/mruby-io/README.md
@@ -4,7 +4,7 @@ mruby-io
 `IO` and `File` classes for mruby
 
 ## Installation
-Add the line below to your `build_config.rb`:
+Add the line below to your build configuration.
 
 ```
   conf.gem core: 'mruby-io'
diff --git a/mrbgems/mruby-io/include/mruby/ext/io.h b/mrbgems/mruby-io/include/mruby/ext/io.h
index dfff8e0e0..1188935ee 100644
--- a/mrbgems/mruby-io/include/mruby/ext/io.h
+++ b/mrbgems/mruby-io/include/mruby/ext/io.h
@@ -8,7 +8,7 @@
 #include <mruby.h>
 
 #ifdef MRB_DISABLE_STDIO
-# error IO and File conflicts 'MRB_DISABLE_STDIO' configuration in your 'build_config.rb'
+# error IO and File conflicts 'MRB_DISABLE_STDIO' in your build configuration
 #endif
 
 #if defined(__cplusplus)
diff --git a/mrbgems/mruby-method/README.md b/mrbgems/mruby-method/README.md
index 5076bfbb2..21ef0a936 100644
--- a/mrbgems/mruby-method/README.md
+++ b/mrbgems/mruby-method/README.md
@@ -10,7 +10,8 @@ p Enumerable.instance_method(:find_all).source_location
 
 # Note
 
-`source_location` method need this configuration in build_config.rb
+You need to enable debug option in your build configuration to use
+`source_location` method in this gem, for example:
 
 ```ruby
 MRuby::Build.new do |conf|
diff --git a/mrbgems/mruby-pack/README.md b/mrbgems/mruby-pack/README.md
index c8a653fba..c66945cde 100644
--- a/mrbgems/mruby-pack/README.md
+++ b/mrbgems/mruby-pack/README.md
@@ -5,7 +5,7 @@ mruby-pack provides `Array#pack` and `String#unpack` for mruby.
 
 
 ## Installation
-Add the line below into your `build_config.rb`:
+Add the line below into your build configuration:
 
 ```
   conf.gem :github => 'iij/mruby-pack'
diff --git a/mrbgems/mruby-print/src/print.c b/mrbgems/mruby-print/src/print.c
index 30b2930b5..588231893 100644
--- a/mrbgems/mruby-print/src/print.c
+++ b/mrbgems/mruby-print/src/print.c
@@ -1,7 +1,7 @@
 #include <mruby.h>
 
 #ifdef MRB_DISABLE_STDIO
-# error print conflicts 'MRB_DISABLE_STDIO' configuration in your 'build_config.rb'
+# error print conflicts 'MRB_DISABLE_STDIO' in your build configuration
 #endif
 
 #include <mruby/string.h>
diff --git a/mrbgems/mruby-sleep/README.md b/mrbgems/mruby-sleep/README.md
index 7707cd040..1c0a86c3a 100644
--- a/mrbgems/mruby-sleep/README.md
+++ b/mrbgems/mruby-sleep/README.md
@@ -2,7 +2,8 @@
 mruby sleep module
 
 ## install by mrbgems
- - add conf.gem line to `build_config.rb`
+- add conf.gem line to your build configuration.
+
 ```ruby
 MRuby::Build.new do |conf|