Merge remote-tracking branch 'upstream/master'

README.md

@@ -11,7 +11,7 @@ You may wonder what's the meaning of JAPL: well, it turns out to be an acronym f
 This project is currently a WIP (Work in Progress) and is not optimized nor complete.
 The design of the language may change at any moment and all the source inside this repo is alpha code quality, for now.  
 
-For other useful information, check the LICENSE file in this repo.  
+For other useful information, check the LICENSE file in this repo.
 
 JAPL is licensed under the Apache 2.0 license.
 
@@ -75,7 +75,7 @@ JAPL is born thanks to the amazing work of Bob Nystrom that wrote a book availab
 ## JAPL - Installing
 
 JAPL is currently in its early stages and is therefore in a state of high mutability, so this installation guide might
-not be always up to date.
+not be always up to date
 
 ### Requirements
 
@@ -95,7 +95,7 @@ git clone https://github.com/japl-lang/japl
 
 ### Running the build script
 
-As a next step, you need to run the build script. This will generate the required configuration files, compile the JAPL runtime and run tests (unless `--skip-tests` is used). There are some settings that can be tweaked with command-line options (or environment variables), for more information, run `python3 build.py --help`.
+As a next step, you need to run JABT (YES, Just Another Build Tool). This will generate the required configuration files, compile the JAPL runtime and run tests (unless `--skip-tests` is used). There are some settings that can be tweaked with command-line options (or environment variables), for more information, run `python3 build.py --help`.
 
 To compile the JAPL runtime, you'll first need to move into the project's directory you cloned before, so run `cd japl`, then `python3 build.py ./src` and wait for it to complete. You should now find an executable named `japl` (or `japl.exe` on windows) inside the `src` folder.
 
@@ -131,9 +131,9 @@ There are also some compile-time constants (such as the heap grow factor for the
 - `map_load_factor` -> A real value between 0 and 1 that indicates the max. % of full buckets in JAPL's hashmap implementation that are needed to trigger a resize
 - `frames_max` - The max. number of call frames allowed, used to limit recursion depth
 
-Each of these options is independent of the others and can be enabled/disabled at will. Except for `array_grow_factor`, `map_load_factor` and `frames_max` (which take integers and a real values respectively), all other options require boolean parameters; to enable an option, pass `option_name:true` to `--options` while to disable it, replace `true` with `false`.
+Each of these options is independent of the others and can be enabled/disabled at will. Except for `array_grow_factor`, `map_load_factor` and `frames_max` (which take integers and a real value respectively), all other options require boolean parameters; to enable an option, pass `option_name:true` to `--options` while to disable it, replace `true` with `false`.
 
-Note that the build tool will generate a file named `config.nim` inside the `src` directory and will use that for subsequent builds, so if you want to override it you'll have to pass `--override-config` as a command-line options. Passing it without any option will fallback to (somewhat) sensible defaults
+Note that the build tool will generate a file named `config.nim` inside the `src` directory and will use that for subsequent builds, so if you want to override it you'll have to enable `--override-config` (via CLI, env. variables or build profiles). Passing it without any other option will fallback to (somewhat) sensible defaults
 
 **P.S.**: For now the test suite assumes that all debugging options are turned off, so for development/debug builds we recommend skipping the test suite by passing `--skip-tests` to the build script. This will be fixed soon (the test suite will ignore debugging output)
 
@@ -151,3 +151,11 @@ the already existing data unless `--ignore-binary` is passed!
 On both Windows and Linux, the build script supports reading parameters from environment variables if they are not specified via the command line.
 All options follow the same naming scheme: `JAPL_OPTION_NAME=value` and will only be applied if no explicit override for them is passed
 when running the script
+
+
+### Build profiles
+
+JABT comes with a handy `--profile` option that allows to pass a JSON file with
+all the build arguments and flags. The JAPL toolsuite comes with some build profiles by default, they are
+found inside the `resources/profiles` directory and are particularly useful to replicate common build options.
+Note that profiles have priority over command-line options and environment variables!

build.py

@@ -18,6 +18,7 @@
 
 import os
 import stat
+import json
 import shlex
 import shutil
 import logging
@@ -143,7 +144,6 @@ def build(path: str, flags: Optional[Dict[str, str]] = {}, options: Optional[Dic
 
     config_path = os.path.join(path, "config.nim")
     main_path = os.path.join(path, "japl.nim")
-    logging.info("Just Another Build Tool, version 0.3.4")
     listing = "\n- {} = {}"
     if not os.path.exists(path):
         logging.error(f"Input path '{path}' does not exist")
@@ -161,6 +161,7 @@ def build(path: str, flags: Optional[Dict[str, str]] = {}, options: Optional[Dic
             return
         else:
             logging.debug(f"Config file has been generated, compiling with options as follows: {''.join(listing.format(k, v) for k, v in options.items())}")
+    logging.debug(f"Nim compiler options: {''.join(listing.format(k, v) for k, v in flags.items())}")
     logging.debug(f"Compiling '{main_path}'")
     nim_flags = " ".join(f"-{name}:{value}" if len(name) == 1 else f"--{name}:{value}" for name, value in flags.items())
     command = "nim {flags} compile {path}".format(flags=nim_flags, path=main_path)
@@ -241,6 +242,7 @@ if __name__ == "__main__":
         parser.add_argument("--skip-tests", help="Skips running the JAPL test suite, useful for debug builds", action="store_true", default=os.getenv("JAPL_SKIP_TESTS"))
         parser.add_argument("--install", help="Tries to move the compiled binary to PATH (this is always disabled on windows)", action="store_true", default=os.environ.get("JAPL_INSTALL"))
         parser.add_argument("--ignore-binary", help="Ignores an already existing 'jpl' binary in any installation directory and overwrites it, use (with care!) with --install", action="store_true", default=os.getenv("JAPL_IGNORE_BINARY"))
+        parser.add_argument("--profile", help="The path to a json file specifying build options and arguments. Overrides ANY other option!", default=os.environ.get("JAPL_PROFILE"))
         args = parser.parse_args()
         flags = {
                 "gc": "refc",
@@ -263,6 +265,7 @@ if __name__ == "__main__":
                             datefmt="%T",
                             level=logging.DEBUG if args.verbose else logging.INFO
                             )
+        logging.info("Just Another Build Tool, version 0.3.4")
         if args.flags:
             try:
                 for value in args.flags.split(","):
@@ -282,6 +285,31 @@ if __name__ == "__main__":
             except Exception:
                 logging.error("Invalid parameter for --options")
                 exit()
+        if args.profile:
+            try:
+                with open(args.profile) as profile:
+                    skip = 0
+                    line = profile.readline()
+                    while line.startswith("//"):
+                        # We skip comments and keep track of
+                        # where we should reset our buffer
+                        skip = profile.tell()
+                        line = profile.readline()
+                    profile.seek(skip - 1)
+                    data = json.load(profile)
+                    if "options" in data:
+                        for option, value in data["options"].items():
+                            options[option] = value
+                    if "flags" in data:
+                        for flag, value in data["flags"].items():
+                            flags[flag] = value
+                    for arg in {"override_config", "skip_tests", "verbose", "install", "ignore_binary"}:
+                        setattr(args, arg, data.get(arg, getattr(args, arg)))
+            except Exception as e:
+                logging.error(f"An error occurred while loading profile '{args.profile}' -> {type(e).__name__}: {e}")
+                exit()
+            else:
+                logging.info(f"Using profile '{args.profile}'")
         build(args.path,
               flags,
               options,

resources/profiles/debug_all.json

@@ -0,0 +1,20 @@
+// Debugs JAPL with both its internal tooling and help from the
+// nim compiler itself (d:debug). The debug build is still optimized
+// for speed with opt:speed
+{"flags": {
+        "gc": "boehm",
+        "d": "debug",
+        "opt": "speed"
+        },
+ "verbose": true,
+ "override_config": true,
+ "skip_tests": true,
+ "install": true,
+ "ignore_binary": true,
+ "options": {
+         "debug_vm": "true",
+         "debug_gc": "true",
+         "debug_compiler": "true",
+         "debug_alloc": "true"
+         }
+}

resources/profiles/debug_alloc.json

@@ -0,0 +1,16 @@
+// Debugs JAPL's memory manager, without any help
+// from nim itself (the nim compiler options are identical to those of
+// production.json)
+{"flags": {
+        "gc": "none",
+        "d": "danger"
+        },
+ "skip_tests": true,
+ "verbose": true,
+ "override_config": true,
+ "install": true,
+ "ignore_binary": true,
+ "options": {
+         "debug_alloc": "true"
+         }
+}

resources/profiles/debug_compiler.json

@@ -0,0 +1,16 @@
+// Debugs the JAPL compiler toolchain, without any help
+// from nim itself (the nim compiler options are identical to those of
+// production.json)
+{"flags": {
+        "gc": "none",
+        "d": "danger"
+        },
+ "skip_tests": true,
+ "verbose": true,
+ "override_config": true,
+ "install": true,
+ "ignore_binary": true,
+ "options": {
+         "debug_compiler": "true"
+         }
+}

resources/profiles/debug_gc.json

@@ -0,0 +1,16 @@
+// Debugs JAPL's garbage collector, without any help
+// from nim itself (the nim compiler options are identical to those of
+// production.json)
+{"flags": {
+        "gc": "none",
+        "d": "danger"
+        },
+ "skip_tests": true,
+ "verbose": true,
+ "override_config": true,
+ "install": true,
+ "ignore_binary": true,
+ "options": {
+         "debug_gc": "true"
+         }
+}

resources/profiles/debug_japl.json

@@ -0,0 +1,19 @@
+// Debugs JAPL with all flags turned on, but without any help
+// from nim itself (the nim compiler options are identical to those of
+// production.json)
+{"flags": {
+        "gc": "none",
+        "d": "danger"
+        },
+ "skip_tests": true,
+ "verbose": true,
+ "override_config": true,
+ "install": true,
+ "ignore_binary": true,
+ "options": {
+         "debug_vm": "true",
+         "debug_gc": "true",
+         "debug_compiler": "true",
+         "debug_alloc": "true"
+         }
+}

resources/profiles/debug_vm.json

@@ -0,0 +1,16 @@
+// Debugs the JAPL Virtual Machine, but without any help
+// from nim itself (the nim compiler options are identical to those of
+// production.json)
+{"flags": {
+        "gc": "none",
+        "d": "danger"
+        },
+ "skip_tests": true,
+ "verbose": true,
+ "override_config": true,
+ "install": true,
+ "ignore_binary": true,
+ "options": {
+         "debug_vm": "true"
+         }
+}

resources/profiles/development.json

@@ -0,0 +1,11 @@
+// Development build options
+{"flags": {
+        "gc": "boehm",
+        "d": "debug",
+        "opt": "speed"
+        },
+ "verbose": true,
+ "override_config": true,
+ "install": true,
+ "ignore_binary": true
+}

resources/profiles/production.json

@@ -0,0 +1,9 @@
+// Production build options
+{"flags": {
+        "gc": "none",
+        "d": "danger"
+        },
+ "override_config": true,
+ "install": true,
+ "ignore_binary": true
+}