[Boost-build] project-root.jam --> Jamroot.jam patch.

From: Jurko Gospodnetiæ (jurko.gospodnetic_at_[hidden])
Date: 2008-01-02 11:16:26

   Hi.

   I remember while first playing around with Boost Build one thing that
really confused me was all the project-root/Jamroot/... terminology.

   Any plans to clean this up?

   My suggestion would be to make Jamroot.jam and Jamfile.jam primary 
names for Boost Build Jamfiles and use those names consistently 
throughout all documentation and all example/test code.

   I prefer using the .jam extension as it makes life much easier on 
Windows where different tools may be configured to treat .jam files in 
some consistent way (automatically open in a certain editor, 
automatically transfer in ASCII mode using FTP, etc...).

   Older variants such as project-root.jam, build.jam, Jamroot, Jamfile, 
etc. should be deprecated and slowly phased out. Older names could me 
made to display a (possibly optional) 'deprecated Jamfile name' warning.

   If its ok, I could do the work and update boost build code but I do 
not know how to supply patches for changing file names and I do not have 
SVN write access.

   I'm attaching a patch changing one related error message, adjusting 
the appropriate Boost Build test and updating some related documentation.

   Hope this helps.

   Best regards,
     Jurko Gospodnetiæ

Renamed some Jamfile and project-root.jam references to Jamfile.jam and
Jamroot.jam respectively.

Left base folder: X:\Boost_Build\20071228_nightly_build\Original
Right base folder: X:\Boost_Build\20071228_nightly_build\Modified
--- boost-build\build\project.jam	2008-01-02 15:08:15.000000000 +-0100
+++ boost-build\build\project.jam	2008-01-02 16:20:39.000000000 +-0100
@@ -106,13 +106,13 @@
     local found = [ path.glob-in-parents $(location) :
       $(JAMROOT) $(JAMFILE) ] ;
 
     if ! $(found)
     {
         ECHO "error: Could not find parent for project at '$(location)'" ;
-        ECHO "error: Did not find Jamfile or project-root.jam in any parent directory." ;
+        ECHO "error: Did not find Jamfile.jam or Jamroot.jam in any parent directory." ;
         EXIT ;
     }
 
     return [ load $(found[1]:D) ] ;
 }
 
--- boost-build\doc\src\extending.xml	2007-12-28 20:48:43.000000000 +-0100
+++ boost-build\doc\src\extending.xml	2008-01-02 16:40:19.000000000 +-0100
@@ -93,24 +93,25 @@
 
 <!-- We use verbatim.inline-file in one place and just inline-file in
              another. Is this confusing for user?
         -->
 </para>
 
-  <para>Now, we're ready to tie it all together. Put all the code
-  above in file <filename>verbatim.jam</filename>, add <code>import verbatim ;</code> 
-  to <filename>project-root.jam</filename>, and it's possible to write
-  the following in Jamfile:</para>
+  <para>
+    Now, we're ready to tie it all together. Put all the code above in file
+    <filename>verbatim.jam</filename>, add <code>import verbatim ;</code> to
+    <filename>Jamroot.jam</filename>, and it's possible to write the following
+    in Jamfile:
+  </para>
 
 <programlisting>
 exe codegen : codegen.cpp class_template.verbatim usage.verbatim ;
 </programlisting>
 
   <para>
-The verbatim files will be automatically converted into C++
-and linked it.
+    The verbatim files will be automatically converted into C++ and linked it.
   </para>
 
       <para>In the subsequent sections, we will extend this example, and review
         all the mechanisms in detail. The complete code is available in <filename>example/customization</filename>
         directory.
       </para>
@@ -720,28 +721,29 @@
 generators.register-standard obfuscate.file : CPP : OBFUSCATED_CPP ;
 </programlisting>
       and import that module, you'll be able to use the rule "obfuscated-cpp"
       in Jamfiles, which will convert source to the OBFUSCATED_CPP type.
     </para>
     
-    <para>The second way is to write a wrapper rule that calls
-      any of the existing rules. For example, suppose you have only one library per
-      directory and want all cpp files in the directory to be compiled into that library. You
-      can achieve this effect with:
+    <para>
+      The second way is to write a wrapper rule that calls any of the existing
+      rules. For example, suppose you have only one library per directory and
+      want all cpp files in the directory to be compiled into that library. You
+      can achieve this effect using:
 <programlisting>
 lib codegen : [ glob *.cpp ] ;
 </programlisting>
-      but if you want to make it even simpler, you could add the following
-      definition to the <filename>project-root.jam</filename> file:
+      If you want to make it even simpler, you could add the following
+      definition to the <filename>Jamroot.jam</filename> file:
 <programlisting>
 rule glib ( name : extra-sources * : requirements * )
 {
     lib $(name) : [ glob *.cpp ] $(extra-sources) : $(requirements) ;
 }
 </programlisting>
-which would allow you to reduce the Jamfile to
+      allowing you to reduce the Jamfile to just
 <programlisting>
 glib codegen ;
 </programlisting>
     </para>
 
     <para>
@@ -754,17 +756,17 @@
   </section>
 
   <section id="bbv2.extending.toolset_modules">
 
     <title>Toolset modules</title>
 
-    <para>If your extensions will be used only on one project, they can be
-      placed in a separate <filename>.jam</filename> file that will be
-      imported by your <filename>project-root.jam</filename>. If the
-      extensions will be used on many projects, users will thank you for 
-      a finishing touch.
+    <para>
+      If your extensions will be used only on one project, they can be placed in
+      a separate <filename>.jam</filename> file and imported by your
+      <filename>Jamroot.jam</filename>. If the extensions will be used on many
+      projects, users will thank you for a finishing touch.
     </para>
 
     <para>The <code>using</code> rule provides a standard mechanism
     for loading and configuring extensions.  To make it work, your module
     <!-- "module" hasn't been defined yet.  Furthermore you haven't
          said anything about where that module file must be
--- boost-build\doc\src\faq.xml	2007-12-28 15:33:28.000000000 +-0100
+++ boost-build\doc\src\faq.xml	2008-01-02 16:36:57.000000000 +-0100
@@ -213,18 +213,18 @@
 local gtk_includes = [ SHELL "gtk-config --cflags" ] ;
 </programlisting>
     </para>
   </section>
 
   <section>
-    <title>How to get the project-root location?
+    <title>How to get the project root (a.k.a. Jamroot.jam) location?
     </title>
 
-    <para>You might want to use the location of the project-root in your
-      Jamfiles. To do it, you'd need to declare path constant in your
-      project-root.jam:
+    <para>
+      You might want to use your project's root location in your Jamfiles. To
+      access it just declare a path constant in your Jamroot.jam file using:
 <programlisting>
 path-constant TOP : . ;
 </programlisting>
       After that, the <code>TOP</code> variable can be used in every Jamfile.
     </para>
   </section>
--- boost-build\test\project_test3.py	2007-12-28 15:33:28.000000000 +-0100
+++ boost-build\test\project_test3.py	2008-01-02 16:20:45.000000000 +-0100
@@ -13,13 +13,13 @@
 
 # First check some startup
 t.set_tree("project-test3")
 os.remove("project-root.jam")
 t.run_build_system(status=1, stdout=
 """error: Could not find parent for project at '.'
-error: Did not find Jamfile or project-root.jam in any parent directory.
+error: Did not find Jamfile.jam or Jamroot.jam in any parent directory.
 
 """)
 
 t.set_tree("project-test3")
 t.run_build_system()