update to release 0.1.061

README.md

@@ -9,7 +9,7 @@ The text is backed by some 300 complete working Jai examples and growing. They a
 Many thanks to Daniel Tan for setting up the [Jai-Community](https://jai.community/) and the [Jai Wiki](https://github.com/Jai-Community/Jai-Community-Library/wiki).
 Also thanks to mehlian, seneca and Jakub Arnold(@darthdeus) for their remarks and contributions.
 
-[Contents adapted and code tested to compile/run with Jai version beta 0.1.060, built on 8 April2023]
+[Text content adapted and code tested to compile/run with Jai version beta 0.1.061, built on 16 April 2023]
 
 _Table of Contents_
 

book/2_Setting_up_a_Jai_Development_Environment.md

@@ -10,7 +10,7 @@ Unzipping this file shows the following contents:
 
 Here is what these folders contain:
 
-- _bin_: this contains the Jai compiler executables (jai.exe for Windows, jai-linux for Linux, see $ 4.1-4.4) and the LLVM linker lld (see section § 4.5).
+- _bin_: this contains the Jai compiler executables (jai.exe for Windows, jai-linux for Linux, jai-macos for MacOs, see $ 4.1-4.4) and the LLVM linker lld (see section § 4.5).
 - *how_to*: this contains some examples with explanatory comments.
 - _examples_: this contains some more advanced example programs.
 - _modules_: this contains Jai’s standard library, we'll discuss this in the rest of the book, in particular in § 6B, 19, 27, 31-34.  
@@ -24,22 +24,22 @@ You can use the extracted folder structure as-is, no installation is needed!
 Unpack the zip file in a temporary folder using:
 
     - On Windows: RIGHT-CLICK the file and select Extract All... 
-    - On Linux (or WSL2 in Windows): use tar -xvf in a terminal
+    - On Linux/MacOs (or WSL2 in Windows): use tar -xvf in a terminal
 
 Now copy the _jai_ subfolder in its entirety to its destination (let's call this the _Jai root folder_), as follows:
 
     - On Windows: for example on the C-drive to c:\jai 
-    - On Linux (or WSL2 in Windows): for example to /usr/local/bin/jai or /opt/jai or $HOME/jai 
+    - On Linux/MacOs (or WSL2 in Windows): for example to /usr/local/bin/jai or /opt/jai or $HOME/jai 
     (assuming $HOME is /home/your_username)
-      Rename jai-linux to jai:  mv jai-linux jai
+      Rename jai-linux or jai-macos to jai:  mv jai-linux jai (same for Jai-macos)
       You also have to make jai and the link program executable with the following commands 
       (perhaps sudo is needed):
           chmod +x jai
-          chmod +x lld-linux
+          chmod +x lld-linux (or chmod +x lld-macos)
 
 Now open a terminal in your Jai root folder, and type the command:  
     - On Windows: `jai -version`
-    - On Linux (or WSL2 in Windows): `./jai -version`
+    - On Linux/MacOs (or WSL2 in Windows): `./jai -version`
 it will show the following output (for your actual version):
 
 _Version: beta 0.1.036, built on 17 August 2022._
@@ -57,13 +57,13 @@ To achieve this, do the following:
         • choose System Variables, Path, click button New, add c:\jai
         • click OK on all open windows 
 
-    - On Linux (or WSL2 in Windows): make a symbolic link like ln -s /path/to/jai/bin/jai /usr/bin/jai
+    - On Linux/MacOs (or WSL2 in Windows): make a symbolic link like ln -s /path/to/jai/bin/jai /usr/bin/jai
         (for example: ln -s $HOME/jai/bin/jai /usr/bin/jai)
 
         Or add this line to your /etc/profile or $HOME/.profile:
         export PATH="$HOME/jai/bin/:$PATH"
 
-        After creating the link, you can run Jai on Linux simply with: `jai`
+        After creating the link, you can run Jai on Linux/MacOs simply with: `jai`
 
 Test this out by moving in a terminal to another folder than the Jai root folder and typing in the command: `jai -version`. You should see the same output as in the previous section.
 
@@ -189,9 +189,9 @@ At this time I recommend the VSCode plugin, because it probably has the most fun
 Visual Studio Code (VSCode) is one of the most popular programmer’s editors today and can be installed from: [VSCode](https://code.visualstudio.com/), it offers lots of basic functionality (code folding, brace pairing, numbering lines, and so on) and a myriad number of extensions.
 There is a VS Code plugin for Jai named _The Language_, which provides basic IDE functionality: [The Language](https://marketplace.visualstudio.com/items?itemName=onelivesleft.the-language).
 
-VSCode is very helpful for editing you source code. Compiling is usually done from the command-line (cmd on Windows or a terminal in Linux), but you can do it also from within VSCode by opening up a New Terminal.
+VSCode is very helpful for editing you source code. Compiling is usually done from the command-line (cmd on Windows or a terminal in Linux/MacOS), but you can do it also from within VSCode by opening up a New Terminal.
 
-> Hint: Whenever you want to search for a procedure (say for example parse_int) in the Jai modules, open VS-code in that folder, select Edit / Find in Files (or the equivalent in your code editor) and fill in `parse_int ::` in the search field. This will only find the definition of parse_int, not all the cases where it is called. In a Linux terminal you can also use `grep -rn 'parse_int ::'`.
+> Hint: Whenever you want to search for a procedure (say for example parse_int) in the Jai modules, open VS-code in that folder, select Edit / Find in Files (or the equivalent in your code editor) and fill in `parse_int ::` in the search field. This will only find the definition of parse_int, not all the cases where it is called. In a Linux/MacOS terminal you can also use `grep -rn 'parse_int ::'`.
 
 ### 2.3.3 How to edit, build and run a Jai program in VS-Code through CodeRunner
 

book/30B_Manipulating the build process.md

@@ -442,19 +442,15 @@ build_debug :: (w: Workspace) {
     print("Choosing debug options...\n");
     target_options := get_build_options(w);
     target_options.backend =.X64; 
-    target_options.optimization_level = .DEBUG;
-    target_options.array_bounds_check = .ON;
-    target_options.output_executable_name = "main3";   
+    set_optimization(*target_options, Optimization_Type.DEBUG, true);
     set_build_options(target_options, w);
 }
 
 build_release :: (w: Workspace) {
     print("Choosing release options...\n");
     target_options := get_build_options(w);
     target_options.backend = .LLVM;
-    target_options.optimization_level = .RELEASE;
-    set_optimization_level(*target_options, 2, 0);
-    target_options.output_executable_name = "main3";   
+    set_optimization(*target_options, Optimization_Type.VERY_OPTIMIZED);   
     set_build_options(target_options, w);
 }
 
@@ -470,18 +466,17 @@ Calling `main3` now shows: main3
 `This program was built with meta-program 30.8_debug_release_build.jai`
 
 `build_debug` shows the recommended debug options:  
-* backend = .X64  
-* optimization_level = .DEBUG
-* array_bounds_check = .ON
+*     target_options.backend =.X64; 
+*     set_optimization(*target_options, Optimization_Type.DEBUG, true);
 
 The X64 backend is faster than the LLVM backend, but for most programs the difference is negligible.
 
 This build compiles faster with as much debugging information as possible, but has some overhead in order to help debug. An executable built in debug mode will, for example, tell the programmer on which line of code the program crashed on, and check for array out of bounds errors. As expected from debug builds, the code is not as optimized as a release build.
 
 `build_release` shows the recommended release options:  
-* backend = .LLVM 
-* optimization_level = .RELEASE
-* set_optimization_level(target_options, 2, 0); // same as clang -O2  
+*     target_options.backend = .LLVM;
+*     set_optimization(*target_options, Optimization_Type.VERY_OPTIMIZED);   
+
 (for a complete overview of release options, check Appendix D: Performance.)
 
 The LLVM compiler backend is slower than the X64 backend, because it does a lot more optimizations. An optimized build does not have debug information built into it, and takes longer to compile. This build makes the compiler produce the best possible optimized code. 
@@ -596,8 +591,8 @@ See *30.10_generate_llvm_bitcode.jai*:
     target_options := get_build_options(w);
     target_options.output_executable_name = "exec";
     target_options.intermediate_path = #filepath;
-    set_optimization_level(*target_options, 2, 0);      // (1)
-    target_options.llvm_options.output_bitcode = true;  // (2)
+    set_optimization(*target_options, Optimization_Type.OPTIMIZED);  // (1)
+    target_options.llvm_options.output_bitcode = true;               // (2)
     set_build_options(target_options, w);
 
     compiler_begin_intercept(w);
@@ -935,8 +930,8 @@ build :: () {
     set_build_options_dc(.{do_output=false});
 
 	options := get_build_options();
-    do_debug := (options.optimization_level == .DEBUG);
-    success := build_cpp_dynamic_lib("cpp_library", "cpp_library.cpp", debug=do_debug);
+    set_optimization(*options, Optimization_Type.DEBUG, true);
+    success := build_cpp_dynamic_lib("cpp_library", "cpp_library.cpp", debug=true);
     if !success {
         compiler_set_workspace_status(.FAILED);
         return;

book/30_Integrated_build_system.md

@@ -243,8 +243,9 @@ build :: () {
     }
     target_options := get_build_options(w);
 
-    target_options.optimization_level = .DEBUG;    
-    target_options.backend = .LLVM;               
+    target_options.backend = .LLVM;  
+    set_optimization(*target_options, Optimization_Type.DEBUG, true);   // (0A)
+    // set_optimization(*target_options, Optimization_Type.OPTIMIZED);  // (0B)
 
     target_options.output_type = .EXECUTABLE;      
     target_options.output_executable_name = "my_program";
@@ -293,25 +294,36 @@ A few of the most important build options are shown in the program above and dis
 ```
 Build_Options for Workspace 3 are: {
     output_type = EXECUTABLE;
+    output_flags = 0;
     Commonly_Propagated = {
-        optimization_level = DEBUG;
         write_added_strings = true;
         runtime_storageless_type_info = true;
         shorten_filenames_in_error_messages = false;
+        use_visual_studio_message_format = false;
 ...
 ```
 ### 30.4.1 The optimization level
-This can be either `.DEBUG` or `.RELEASE`, for example:   
-`target_options.optimization_level = .RELEASE;`
-
-For a highly optimized build, having the same effect as `clang -O2`, you would use:
+This is set with the procedure `set_optimization`, for example:   
+`set_optimization(*target_options, Optimization_Type.DEBUG, true);`     
+for debug, or:  
+`set_optimization(*target_options, Optimization_Type.OPTIMIZED);`   
+for release.
+The Optimization_Type enum values defined in module `Compiler` are:  
 ```c++
-set_optimization_level(*target_options, 2, 0); 
+    DEBUG                :: 0;
+    VERY_DEBUG           :: 1;
+    OPTIMIZED            :: 2;
+    VERY_OPTIMIZED       :: 3;
+    OPTIMIZED_SMALL      :: 4;
+    OPTIMIZED_VERY_SMALL :: 5; 
 ```
-Optimized builds take much longer (10x) time than debug builds, but are around 2x as fast as an un-optimized build.
 
+Optimized builds take much longer (10x) time than debug builds, but are around 2x as fast as an un-optimized build.
 This automatically turns OFF all runtime checks, and specifies a number of optimizations for LLVM code production.
 
+**Remark**
+Most (if not all) optimization settings included in `30.4_build_options.jai` are automatically turned on or off by using `set_optimization` with the appropriate `Optimization_Type` enum values. They are added here only so that we can discuss them. In a normal program `set_optimization` is sufficient, you would not have to add additional optimization settings.
+
 To enable bytecode inlining, use: `target_options.enable_bytecode_inliner = true;`   
 To stop making a .pdb file, use:  `target_options.emit_debug_info=.NONE;`
 

book/33_Graphical modules.md

@@ -1166,5 +1166,5 @@ manifest_options.dpi_aware = false;
 add_manifest_to_executable(exe_name, manifest_options);
 ```
 
-Because this feature is specific for Windows, you might place this code in a ` #if OS == .WINDOWS { }` section.
+Because this feature is specific for Windows, you might want to place this code in a ` #if OS == .WINDOWS { }` section.
 

book/4_More_info_about_the_compiler.md

@@ -64,7 +64,7 @@ _Compiler  time: 0.587162 seconds._
 	Front-end time + llvm time = Compiler time (for llvm backend)
 
 ## 4.5 Linking
-The backend compiler produces several compiler artifacts in the hidden _.build_ folder (.obj, .exp and .lib files). It is the task of the linker (_link.exe_ from MSVC on Windows, _lld-linux_ on Linux) to combine these object files and (sometimes) OS specific libraries statically into one output executable (.exe on Windows).  
+The backend compiler produces several compiler artifacts in the hidden _.build_ folder (.obj, .exp and .lib files). It is the task of the linker (_link.exe_ from MSVC on Windows, _lld-linux_ on Linux, _lld-macos_ on MacOs ) to combine these object files and (sometimes) OS specific libraries statically into one output executable (.exe on Windows).  
 The time this takes is for example reported as:   
 _Link      time: 0.328986 seconds._
 
@@ -89,7 +89,7 @@ Total     time: 0.425573 seconds.
 One of the big advantages of LLVM is that it is _platform independent_: it can produce executable binary code for a wide variety of platforms, amongst them game consoles.  
 Specifically at this time, Jai supports:  
     • 	x86 architecture only (limited Nintendo Switch support).  
-    • 	OS / Platforms: Windows, Ubuntu Linux, limited Mac support, at least one gaming console
+    • 	OS / Platforms: Windows, (Ubuntu) Linux, MacOs support, at least one gaming console
 
 ## 4.7 Debug and release build
 While developing, you’ll work with normal _debug builds_ which is the default, because you want to have as much info as possible when something goes wrong. For example a .pdb file with debugging info is produced, stack trace info will be shown, and optimizations which can hide erroneous behavior must be disabled.

examples/30/30.10_generate_llvm_bitcode.jai

@@ -10,7 +10,7 @@
     target_options := get_build_options(w);
     target_options.output_executable_name = "exec";
     target_options.intermediate_path = #filepath;
-    set_optimization_level(*target_options, 2, 0);      // (1)
+    set_optimization(*target_options, Optimization_Type.OPTIMIZED);  // (1)
     target_options.llvm_options.output_bitcode = true;  // (2)
     set_build_options(target_options, w);
 

examples/30/30.4_build_options.jai

@@ -9,9 +9,9 @@ build :: () {
     }
     target_options := get_build_options(w);
 
-    target_options.optimization_level = .DEBUG;   
-
     target_options.backend = .LLVM;               
+    set_optimization(*target_options, Optimization_Type.DEBUG, true);   // (0A)
+    // set_optimization(*target_options, Optimization_Type.OPTIMIZED);  // (0B)
 
     target_options.output_type = .EXECUTABLE;      
     target_options.output_executable_name = "my_program";
@@ -51,7 +51,6 @@ Build_Options for Workspace 3 are: {
     output_type = EXECUTABLE;
     output_flags = 0;
     Commonly_Propagated = {
-        optimization_level = DEBUG;
         write_added_strings = true;
         runtime_storageless_type_info = true;
         shorten_filenames_in_error_messages = false;

examples/30/30.8_debug_release_build.jai

@@ -1,4 +1,3 @@
-// Error: Build_Options.output_type is set to EXECUTABLE, but Build_Options.output_executable_name is empty.
 #import "Basic";
 #import "Compiler";
 
@@ -27,17 +26,15 @@ build_debug :: (w: Workspace) {
     print("Choosing debug options...\n");
     target_options := get_build_options(w);
     target_options.backend =.X64; 
-    target_options.optimization_level = .DEBUG;
-    target_options.array_bounds_check = .ON;
+    set_optimization(*target_options, Optimization_Type.DEBUG, true);
     set_build_options(target_options, w);
 }
 
 build_release :: (w: Workspace) {
     print("Choosing release options...\n");
     target_options := get_build_options(w);
     target_options.backend = .LLVM;
-    target_options.optimization_level = .RELEASE;
-    set_optimization_level(*target_options, 2, 0);
+    set_optimization(*target_options, Optimization_Type.VERY_OPTIMIZED);   
     set_build_options(target_options, w);
 }
 

examples/30/cpp_library/.build/.added_strings_w2.jai

@@ -0,0 +1,50 @@
+// Workspace: Target Program
+//
+// #insert text. Generated from c:/jai/modules/Bindings_Generator/module.jai:288.
+//
+    ([2] string).[
+        .["FLT_MIN", "FLOAT32_MIN"],
+        .["FLT_MAX", "FLOAT32_MAX"],
+        .["DBL_MIN", "FLOAT64_MIN"],
+        .["DBL_MAX", "FLOAT64_MAX"],
+
+        .["SCHAR_MIN", "S8_MIN"],
+        .["SCHAR_MAX", "S8_MAX"],
+        .["UCHAR_MIN", "0"],
+        .["UCHAR_MAX", "U8_MAX"],
+
+        .["SHRT_MIN",  "S16_MIN"],
+        .["SHRT_MAX",  "S16_MAX"],
+        .["USHRT_MIN", "0"],
+        .["USHRT_MAX", "U16_MAX"],
+
+        .["INT_MIN",  "S32_MIN"],
+        .["INT_MAX",  "S32_MAX"],
+        .["UINT_MIN", "0"],
+        .["UINT_MAX", "U32_MAX"],
+
+        .["LLONG_MIN", "S64_MIN"],
+        .["LLONG_MAX", "S64_MAX"],
+        .["ULLONG_MIN", "0"],
+        .["ULLONG_MAX", "U64_MAX"],
+
+        .["INT8_MIN", "S8_MIN"],
+        .["INT8_MAX", "S8_MAX"],
+        .["UINT8_MAX", "U8_MAX"],
+
+        .["INT16_MIN", "S16_MIN"],
+        .["INT16_MAX", "S16_MAX"],
+        .["UINT16_MAX", "U16_MAX"],
+
+        .["INT32_MIN", "S32_MIN"],
+        .["INT32_MAX", "S32_MAX"],
+        .["UINT32_MAX", "U32_MAX"],
+
+        .["INT64_MIN", "S64_MIN"],
+        .["INT64_MAX", "S64_MAX"],
+        .["UINT64_MAX", "U64_MAX"],
+            .["LONG_MIN", "S32_MIN"],
+            .["LONG_MAX", "S32_MAX"],
+            .["ULONG_MIN", "0"],
+            .["ULONG_MAX", "U32_MAX"],
+];

examples/30/cpp_library/first.jai

@@ -8,8 +8,8 @@ build :: () {
     set_build_options_dc(.{do_output=false});
 
 	options := get_build_options();
-    do_debug := (options.optimization_level == .DEBUG);
-    success := build_cpp_dynamic_lib("cpp_library", "cpp_library.cpp", debug=do_debug);
+    set_optimization(*options, Optimization_Type.DEBUG, true);
+    success := build_cpp_dynamic_lib("cpp_library", "cpp_library.cpp", debug=true);
     if !success {
         compiler_set_workspace_status(.FAILED);
         return;