Browse Source

Initial commit -- added some preliminry planning

thajohns 7 months ago
commit
652634c60d
5 changed files with 109 additions and 0 deletions
  1. 2
    0
      .gitignore
  2. 10
    0
      Cargo.toml
  3. 2
    0
      README.md
  4. 28
    0
      concept.md
  5. 67
    0
      plan.md

+ 2
- 0
.gitignore View File

@@ -0,0 +1,2 @@
1
+/target
2
+**/*.rs.bk

+ 10
- 0
Cargo.toml View File

@@ -0,0 +1,10 @@
1
+[package]
2
+name = "buildsys"
3
+version = "0.1.0"
4
+authors = ["thajohns <thajohns@clarkson.edu>"]
5
+edition = "2018"
6
+
7
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
8
+
9
+[dependencies]
10
+lua = "*"

+ 2
- 0
README.md View File

@@ -0,0 +1,2 @@
1
+The project has ambitious plans to become an automation build tool with a focus on compile-time configuration.
2
+However, it is currently very incomplete. See `plan.md` for more details on what this project aims to be.

+ 28
- 0
concept.md View File

@@ -0,0 +1,28 @@
1
+The following sections are imagined to be subsections of a longer, currently incomplete document.
2
+
3
+## Providers and Providing
4
+
5
+Oftentimes, it makes sense to select one of several different pieces of code to compile.
6
+For example, the reason this tool was created was for an operating system.
7
+The operating system can be compiled for one or more architectures, but they all
8
+*provide* a common set of features. Similarly, a video game may allow for the selection
9
+of one of multiple graphics backends.
10
+
11
+For these cases, this tool has a notion of *providers*. Providers are components that
12
+*provide* a certain feature. Providers are used in dependency resolution in the build
13
+stage. Rather than specify a path to a build file, specify a feature which is provided.
14
+(Specifying a path will work, as paths are automatically added as provided features;
15
+see the below section, "Features", for details.)
16
+
17
+### Features
18
+
19
+Internally, a feature is just a string, and can be arbitrary. However, a style is recommended.
20
+A feature string should consist of a relevant path (relative to the source
21
+root, and followed by a trailing slash), then a colon, then the name of a feature.
22
+The default build file of a directory will automatically provide the feature corresponding
23
+to that directory name, but with no colon or feature name.
24
+
25
+### Configuration Settings as Providers
26
+
27
+TODO - but the gist is to allow, e.g., different sets of enumeration values based on some other setting.
28
+Thus, predicates can be between providers, and providing can be dependent on a predicate.

+ 67
- 0
plan.md View File

@@ -0,0 +1,67 @@
1
+Most features mentioned in `concept.md` are currently unimplemented.
2
+One goal is to establish a checklist here.
3
+
4
+# Overview
5
+
6
+This project aims to create a build automation tool that is language- and tooling-agnostic, somewhat
7
+portable, not too much of a hassle to use, and specialized for complex compile-time configuration.
8
+
9
+In lieu of writing a custom description language, the build descriptor files will be written in
10
+Lua, and will call functions to manipulate data structures that the file describes. (This also
11
+provides freedom and scriptablity not found in many other build systems.)
12
+
13
+This tool will not build projects by itself; rather, it will generate Ninja files, then invoke Ninja.
14
+
15
+# Workflow
16
+
17
+Configuration and file generation will (at least internally) be done in two separate passes. 
18
+
19
+Roughly, the workflow will be as follows: First, the project will be configured. In this
20
+step, a function in the root component's (and its transitive component dependencies') build file
21
+will be run which describes the predicates relating different configuration options.
22
+Configuration-time component dependencies will be dynamic (also specified via predicates), and
23
+will change as configuration options get changed.
24
+
25
+Second, the build files will be generated from the given configuration. In this step, a different
26
+function will be run which descibes the dependency graph, which will then be converted to Ninja
27
+build files. Additionally in this step, any tools must be defined. (Tools are the actual Ninja
28
+rules for invoking tools, such as gcc.)
29
+
30
+Third, Ninja will be used to build the project. This step is largely independent of this tool.
31
+
32
+TODO: Decide whether component dependencies will be resolved at configure time or generation time.
33
+
34
+# Configuration
35
+
36
+The configuration dependency engine will be complicated enough to do SAT solving.
37
+As a result of this lofty goal, its implementation will be put off as the last feature to be
38
+implemented, unless sommebody gets bored.
39
+
40
+Each configuration setting will have two intrinsic attributes: its value, and whether or not it exists.
41
+Existing is, by default, equivalent to the existence of the component. When an item does not exist, any
42
+predicate involving it is assumed to be satisfied and will not affect the build.
43
+
44
+Predicates can be built with either of the two intrinsic attributes, including existence.
45
+
46
+## Values
47
+
48
+The simplest type of value will be an enumeration, whether it's T/F, or a set of possible architectures.
49
+Predicates involving enumerations are whether or not they have a certain value.
50
+
51
+The next type of value will be integers. A rudimentary theory of integers will be required, and predicates
52
+involving integers will concern equality and comparison.
53
+
54
+There will also eventually be string values. Predicates about string values will include integer predicates
55
+about string length, prefixes and suffixes, and others as the need arises.
56
+
57
+# Building
58
+
59
+TODO
60
+Most of the burden of ensuring consistency between configuration options and build behavior will
61
+probably be left to the users.
62
+
63
+# Build Dependencies
64
+
65
+TODO - probably via detectors written in Lua and a cache file
66
+Not an important feature for now. Push off until later.
67
+

Loading…
Cancel
Save