Simplified package declaration for the Main package (#2550)

Make the preamble of simple programs more ergonomic, by removing the
`package Main` from the main package and removing the `package`
declaration
entirely from the main source file. Imports within a single package no
longer
need to, and are not permitted to, specify the package name.

Partially covers #2001 / #1136.
Covers #1869.
Supersedes #2265.
Addresses design idea #2323.

---------

Co-authored-by: Jon Ross-Perkins <[email protected]>
Co-authored-by: josh11b <[email protected]>

docs/design/README.md

@@ -74,6 +74,8 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
     -   [Files, libraries, packages](#files-libraries-packages)
     -   [Package declaration](#package-declaration)
     -   [Imports](#imports)
+        -   [Same-package imports](#same-package-imports)
+        -   [Cross-package imports](#cross-package-imports)
     -   [Name visibility](#name-visibility)
     -   [Package scope](#package-scope)
     -   [Namespaces](#namespaces)
@@ -2095,16 +2097,12 @@ to coordinate to avoid name conflicts, but not across packages.
 
 ### Package declaration
 
-> **Note:** This is provisional, designs for a default package, making the
-> package name optional, and omitting the `package` declaration have not been
-> through the proposal process yet. See
-> [#2323](https://github.com/carbon-language/carbon-lang/issues/2323).
-
 Files start with an optional package declaration, consisting of:
 
--   the `package` keyword introducer,
--   an optional identifier specifying the package name,
--   optional `library` followed by a string with the library name,
+-   optionally, the `package` keyword followed by an identifier specifying the
+    package name,
+-   optionally, the `library` keyword followed by a string with the library
+    name,
 -   either `api` or `impl`, and
 -   a terminating semicolon (`;`).
 
@@ -2119,60 +2117,52 @@ package Geometry library "Shapes" api;
 
 Parts of this declaration may be omitted:
 
--   If the package name is omitted, as in `package library "Main" api;`, the
-    file contributes to the default package. No other package may import from
-    the default package.
+-   If the package keyword is not specified, as in `library "Widgets" api;`, the
+    file contributes to the `Main` package. No other package may import from the
+    `Main` package, and it cannot be named explicitly.
 
 -   If the library keyword is not specified, as in `package Geometry api;`, this
     file contributes to the default library.
 
--   If a file has no package declaration at all, it is the `api` file belonging
-    to the default package and default library. This is particularly for tests
-    and smaller examples. No other library can import this library even from
-    within the default package. It can be split across multiple `impl` files
-    using a `package impl;` package declaration.
+-   If both keywords are omitted, the package declaration must be omitted
+    entirely. In this case, the file is an `impl` file belonging to the default
+    library of the `Main` package, which implicitly has an empty `api` file.
+    This library is used to define the entry point for the program, and tests
+    and smaller examples may choose to reside entirely within this library. No
+    other library can import this library even from within the default package.
+
+If the default library of the `Main` package contains a function named `Run`,
+that function is the program entry point. Otherwise, the program's entry point
+may be defined in another language, such as by defining a C++ `main` function.
 
-A program need not use the default package, but if it does, it should contain
-the entry-point function. By default, the entry-point function is `Run` from the
-default package.
+> **Note:** Valid signatures for the entry point have not yet been decided.
 
 > References:
 >
 > -   [Code and name organization](code_and_name_organization)
 > -   Proposal
 >     [#107: Code and name organization](https://github.com/carbon-language/carbon-lang/pull/107)
+> -   Proposal
+>     [#2550: Simplified package declaration for the main package](https://github.com/carbon-language/carbon-lang/pull/2550)
 
 ### Imports
 
-> **Note:** This is provisional, designs for making the package name optional
-> have not been through the proposal process yet. See
-> [#2001](https://github.com/carbon-language/carbon-lang/issues/2001).
+After the package declaration, files may include `import` declarations. The
+`import` keyword is followed by the package name, `library` followed by the
+library name, or both. If the library is omitted, the default library for that
+package is imported.
 
-After the package declaration, files may include `import` declarations. These
-include the package name and optionally `library` followed by the library name.
-If the library is omitted, the default library for that package is imported.
-
-```carbon
-// Import the "Vector" library from the
-// `LinearAlgebra` package.
-import LinearAlgebra library "Vector";
-// Import the default library from the
-// `ArbitraryPrecision` package.
-import ArbitraryPrecision;
-```
+All `import` declarations must appear before all other non-`package`
+declarations in the file.
 
-The syntax `import PackageName ...` introduces the name `PackageName` as a
-[`private`](#name-visibility) name naming the given package. It cannot be used
-to import libraries of the current package. Importing additional libraries from
-that package makes additional members of `PackageName` visible.
+#### Same-package imports
 
-Libraries from the current package are imported by omitting the package name.
+The package name must be omitted when importing a library from the current
+package.
 
 ```carbon
-// Import the "Vertex" library from the same package.
+// Import the "Vertex" library from the package containing this file.
 import library "Vertex";
-// Import the default library from the same package.
-import library default;
 ```
 
 The `import library ...` syntax adds all the public top-level names within the
@@ -2181,15 +2171,62 @@ given library to the top-level scope of the current file as
 [namespaces](#namespaces).
 
 Every `impl` file automatically imports the `api` file for its library.
+Attempting to perform an import of the current library is invalid.
 
-All `import` declarations must appear before all other non-`package`
-declarations in the file.
+```
+package MyPackage library "Widgets" impl;
+
+// ❌ Error, this import is performed implicitly.
+import MyPackage library "Widgets";
+```
+
+The default library for a package does not have a string name, and is instead
+named with the `default` keyword.
+
+```carbon
+// Import the default library from the same package.
+import library default;
+```
+
+It is an error to use the `import library default;` syntax in the `Main`
+package.
+
+#### Cross-package imports
+
+When the package name is specified, the `import` declaration imports a library
+from another package.
+
+```carbon
+package MyPackage impl;
+
+// Import the "Vector" library from the `LinearAlgebra` package.
+import LinearAlgebra library "Vector";
+
+// Import the default library from the `ArbitraryPrecision` package.
+import ArbitraryPrecision;
+```
+
+The syntax `import PackageName ...` introduces the name `PackageName` as a
+[`private`](#name-visibility) name naming the given package. Importing
+additional libraries from that package makes additional members of `PackageName`
+visible.
+
+It is an error to specify the name of the current package. The package name must
+be omitted when [importing from the same package](#same-package-imports).
+
+It is an error to specify `library default` in a package-qualified import.
+Instead, omit the `library` portion of the declaration.
+
+It is an error to specify the package name `Main`. Libraries in the `Main`
+package can only be imported from within that package.
 
 > References:
 >
 > -   [Code and name organization](code_and_name_organization)
 > -   Proposal
 >     [#107: Code and name organization](https://github.com/carbon-language/carbon-lang/pull/107)
+> -   Proposal
+>     [#2550: Simplified package declaration for the main package](https://github.com/carbon-language/carbon-lang/pull/2550)
 
 ### Name visibility