diff --git a/docs/project/principles/README.md b/docs/project/principles/README.md index 173afd5f88859..b301818e566b9 100644 --- a/docs/project/principles/README.md +++ b/docs/project/principles/README.md @@ -27,3 +27,4 @@ wants to pursue, as well as those we want to exclude. - [Prefer providing only one way to do a given thing](one_way.md) - [One static open extension mechanism](static_open_extension.md) - [Success criteria](success_criteria.md) +- [File concatenation](file_concatenation.md) diff --git a/docs/project/principles/file_concatenation.md b/docs/project/principles/file_concatenation.md new file mode 100644 index 0000000000000..b78dbeb2321f4 --- /dev/null +++ b/docs/project/principles/file_concatenation.md @@ -0,0 +1,50 @@ +# Principle: File concatenation should preserve meaning + + + + + +## Table of contents + +- [Abstract](#abstract) +- [Background](#background) +- [Principle](#principle) +- [Applications of these principles](#applications-of-these-principles) + + + +## Abstract + +It's always possible to concat together Carbon source files without changing the +meaning of or diagnostics applied to the code. + +## Background + +In C++, it is a common practice to concatenate files together in order to +recreate and distribute a bug repro or to build a piece of C++ code in an +environment without the requirement of a build system. This allows code taken +from any build environment to be easily compiled by a developer in any other +environment, through a single compiler invocation. + +The reason this works is largely historical, as #include performs a textual +inclusion, but it can be maintained without textual includes as well. + +## Principle + +Concatenating any two Carbon files together will not change the meaning of the +code in either file. It will be required to order the concatenation so that +dependencies are ordered first, in order to maintain the information +accumulation principle. There is always an ordering that allows any Carbon +project to be fully concatenated into a single Carbon source file and thus built +with a single compiler invocation. + +## Applications of these principles + +Carbon uses syntax to denote the start of a library or package, which functions +at the top of a file or in the middle of a file in the same way. Language rules +may change behaviour and/or diagnostics based on the relationship of code +between libraries or packages, but not between files.