Merge pull request #4946 from sizious/sega-dreamcast-example

Improving comments in the cross-compiling sample for the Sega Dreamcast.

examples/targets/build_config_dreamcast_shelf.rb

 MRuby::Build.new do |conf|
-
-  # Gets set by the VS command prompts.
+  # Gets set by the VS command prompts
   if ENV['VisualStudioVersion'] || ENV['VSINSTALLDIR']
     toolchain :visualcpp
   else
@@ -9,27 +8,31 @@ MRuby::Build.new do |conf|
 
   enable_debug
 
-  # include the default GEMs
+  # Include the default GEMs
   conf.gembox 'default'
-
 end
 
-# Cross Compiling configuration for Sega Dreamcast
-# This requires KallistiOS to be installed
+# Cross Compiling configuration for the Sega Dreamcast
+# This configuration requires KallistiOS (KOS)
 # https://dreamcast.wiki
 #
+# Tested on GNU/Linux, MinGW-w64/MSYS2, Cygwin, macOS and MinGW/MSYS (see below)
+#
 MRuby::CrossBuild.new("dreamcast") do |conf|
   toolchain :gcc
 
-  # Supporting DreamSDK (if necessarys)
+  # Support for DreamSDK (based on MinGW/MSYS)
+  # To compile mruby with DreamSDK, RubyInstaller for Windows should be installed
   DREAMSDK_HOME = ENV["DREAMSDK_HOME"]
   MSYS_ROOT = !(DREAMSDK_HOME.nil? || DREAMSDK_HOME.empty?) ? "#{DREAMSDK_HOME}/msys/1.0" : ""
-  
-  # For all host systems
+ 
+  # Setting paths
   DREAMCAST_PATH = "#{MSYS_ROOT}/opt/toolchains/dc"
   KOS_PATH = "#{DREAMCAST_PATH}/kos"
   BIN_PATH = "#{DREAMCAST_PATH}/sh-elf/bin"
 
+  # C compiler
+  # Flags were extracted from KallistiOS environment files
   conf.cc do |cc|
     cc.command = "#{BIN_PATH}/sh-elf-gcc"	
     cc.include_paths << ["#{KOS_PATH}/include", "#{KOS_PATH}/kernel/arch/dreamcast/include", "#{KOS_PATH}/addons/include", "#{KOS_PATH}/../kos-ports/include"]
@@ -39,6 +42,7 @@ MRuby::CrossBuild.new("dreamcast") do |conf|
     cc.defines << %w(_arch_sub_pristine)
   end
 
+  # C++ compiler
   conf.cxx do |cxx|
     cxx.command = conf.cc.command.dup
     cxx.include_paths = conf.cc.include_paths.dup
@@ -47,28 +51,34 @@ MRuby::CrossBuild.new("dreamcast") do |conf|
     cxx.defines = conf.cc.defines.dup
     cxx.compile_options = conf.cc.compile_options.dup
   end
-  
+ 
+  # Linker
+  # There is an issue when making the mruby library with KallistiOS:
+  # 'newlib_kill.o' and 'newlib_getpid.o' aren't found so they are explicitly 
+  # specified here at least for now.
   conf.linker do |linker|
     linker.command="#{BIN_PATH}/sh-elf-gcc"
-	linker.flags << ["#{MSYS_ROOT}/opt/toolchains/dc/kos/kernel/build/newlib_kill.o", "#{MSYS_ROOT}/opt/toolchains/dc/kos/kernel/build/newlib_getpid.o", "-Wl,--start-group -lkallisti -lc -lgcc -Wl,--end-group"]
+    linker.flags << ["#{MSYS_ROOT}/opt/toolchains/dc/kos/kernel/build/newlib_kill.o", "#{MSYS_ROOT}/opt/toolchains/dc/kos/kernel/build/newlib_getpid.o", "-Wl,--start-group -lkallisti -lc -lgcc -Wl,--end-group"]
     linker.library_paths << ["#{KOS_PATH}/lib/dreamcast", "#{KOS_PATH}/addons/lib/dreamcast", "#{KOS_PATH}/../kos-ports/lib"]
   end  
 
+  # Archiver
   conf.archiver do |archiver|
     archiver.command = "#{BIN_PATH}/sh-elf-ar"
     archiver.archive_options = 'rcs %{outfile} %{objs}'
   end
 
-  #no executables
+  # No executables
   conf.bins = []
 
-  #do not build executable test
+  # Do not build executable test
   conf.build_mrbtest_lib_only
 
-  #disable C++ exception
+  # Disable C++ exception
   conf.disable_cxx_exception
   
-  #gems from core
+  # Gems from core
+  # removing mruby-io
   conf.gem :core => "mruby-metaprog"
   conf.gem :core => "mruby-pack"
   conf.gem :core => "mruby-sprintf"