Skip to content

Commit f11ce9b

Browse files
stephentyronestephentyrone
authored
Merge branch 'biginteger' into BigInt
2 parents 935eac1 + 5428505 commit f11ce9b

File tree

77 files changed

+6958
-1333
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

77 files changed

+6958
-1333
lines changed

‎.github/workflows/macos.yml

Lines changed: 0 additions & 15 deletions
This file was deleted.

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@
44
/Packages
55
/*.xcodeproj
66
/.swiftpm
7+
.*.sw?

‎.xcodesamplecode.plist

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎CMakeLists.txt

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
#[[
2+
This source file is part of the Swift Numerics open source project
3+
4+
Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors
5+
Licensed under Apache License v2.0 with Runtime Library Exception
6+
7+
See https://swift.org/LICENSE.txt for license information
8+
#]]
9+
10+
cmake_minimum_required(VERSION 3.16)
11+
project(swift-numerics
12+
LANGUAGES Swift)
13+
14+
list(APPEND CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake/modules)
15+
16+
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
17+
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
18+
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
19+
set(CMAKE_Swift_MODULE_DIRECTORY ${CMAKE_BINARY_DIR}/swift)
20+
21+
include(CTest)
22+
include(SwiftSupport)
23+
24+
add_subdirectory(Sources)
25+
if(BUILD_TESTING)
26+
add_subdirectory(Tests)
27+
endif()
28+
29+
get_property(SWIFT_NUMERICS_EXPORTS GLOBAL PROPERTY SWIFT_NUMERICS_EXPORTS)
30+
export(TARGETS ${SWIFT_NUMERICS_EXPORTS}
31+
NAMESPACE SwiftNumerics::
32+
FILE swift-numerics-config.cmake
33+
EXPORT_LINK_INTERFACE_LIBRARIES)

‎Package.swift

Lines changed: 87 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
// swift-tools-version:5.0
1+
// swift-tools-version:5.4
22
//===--- Package.swift ----------------------------------------*- swift -*-===//
33
//
44
// This source file is part of the Swift Numerics open source project
55
//
6-
// Copyright (c) 2019 - 2020 Apple Inc. and the Swift Numerics project authors
6+
// Copyright (c) 2019-2021 Apple Inc. and the Swift Numerics project authors
77
// Licensed under Apache License v2.0 with Runtime Library Exception
88
//
99
// See https://swift.org/LICENSE.txt for license information
@@ -12,25 +12,97 @@
1212

1313
import PackageDescription
1414

15+
let excludedFilenames = ["CMakeLists.txt", "README.md"]
16+
1517
let package = Package(
18+
1619
name: "swift-numerics",
1720
products: [
1821
.library(name: "BigIntModule", targets: ["BigIntModule"]),
19-
.library(name: "Complex", targets: ["Complex"]),
22+
.library(name: "ComplexModule", targets: ["ComplexModule"]),
2023
.library(name: "Numerics", targets: ["Numerics"]),
21-
.library(name: "Real", targets: ["Real"]),
22-
],
23-
dependencies: [
24+
.library(name: "RealModule", targets: ["RealModule"]),
2425
],
26+
2527
targets: [
26-
.target(name: "BigIntModule", dependencies: []),
27-
.target(name: "Complex", dependencies: ["Real"]),
28-
.target(name: "Numerics", dependencies: ["BigIntModule", "Complex", "Real"]),
29-
.target(name: "NumericsShims", dependencies: []),
30-
.target(name: "Real", dependencies: ["NumericsShims"]),
31-
32-
.testTarget(name: "BigIntTests", dependencies: ["BigIntModule"]),
33-
.testTarget(name: "ComplexTests", dependencies: ["Complex", "NumericsShims"]),
34-
.testTarget(name: "RealTests", dependencies: ["Real"]),
28+
// MARK: - Public API
29+
.target(
30+
name: "BigIntModule",
31+
dependencies: []
32+
),
33+
34+
.target(
35+
name: "ComplexModule",
36+
dependencies: ["RealModule"],
37+
exclude: excludedFilenames
38+
),
39+
40+
.target(
41+
name: "IntegerUtilities",
42+
dependencies: [],
43+
exclude: excludedFilenames
44+
),
45+
46+
.target(
47+
name: "Numerics",
48+
dependencies: ["ComplexModule", "IntegerUtilities", "RealModule"],
49+
exclude: excludedFilenames
50+
),
51+
52+
.target(
53+
name: "RealModule",
54+
dependencies: ["_NumericsShims"],
55+
exclude: excludedFilenames
56+
),
57+
58+
// MARK: - Implementation details
59+
.target(
60+
name: "_NumericsShims",
61+
exclude: excludedFilenames,
62+
linkerSettings: [.linkedLibrary("m", .when(platforms: [.linux, .android]))]
63+
),
64+
65+
.target(
66+
name: "_TestSupport",
67+
dependencies: ["Numerics"],
68+
exclude: ["CMakeLists.txt"]
69+
),
70+
71+
// MARK: - Unit test bundles
72+
.testTarget(
73+
name: "BigIntTests",
74+
dependencies: ["BigIntModule"]
75+
),
76+
77+
.testTarget(
78+
name: "ComplexTests",
79+
dependencies: ["_TestSupport"],
80+
exclude: ["CMakeLists.txt"]
81+
),
82+
83+
.testTarget(
84+
name: "IntegerUtilitiesTests",
85+
dependencies: ["IntegerUtilities", "_TestSupport"],
86+
exclude: ["CMakeLists.txt"]
87+
),
88+
89+
.testTarget(
90+
name: "RealTests",
91+
dependencies: ["_TestSupport"],
92+
exclude: ["CMakeLists.txt"]
93+
),
94+
95+
// MARK: - Test executables
96+
.executableTarget(
97+
name: "ComplexLog",
98+
dependencies: ["Numerics", "_TestSupport"],
99+
path: "Tests/Executable/ComplexLog"
100+
),
101+
102+
.executableTarget(
103+
name: "ComplexLog1p",
104+
dependencies: ["Numerics", "_TestSupport"],
105+
path: "Tests/Executable/ComplexLog1p"
106+
)
35107
]
36108
)

‎README.md

Lines changed: 98 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,139 @@
11
# Swift Numerics
22

33
## Introduction
4+
45
Swift Numerics provides a set of modules that support numerical computing in Swift.
56
These modules fall broadly into two categories:
67

78
- API that is too specialized to go into the standard library, but which is sufficiently general to be centralized in a single common package.
89
- API that is under active development toward possible future inclusion in the standard library.
910

10-
There is some overlap between these two categories, and API that begins in the first category may migrate to the second as it matures and new uses are discovered.
11+
There is some overlap between these two categories, and an API that begins in the first category may migrate into the second as it matures and new uses are discovered.
12+
13+
Swift Numerics modules are fine-grained.
14+
For example, if you need support for Complex numbers, you can import ComplexModule[^1] as a standalone module:
1115

12-
Swift Numerics modules are fine-grained; if you need support for Complex numbers, you can import the Complex module without pulling in everything else in the library as well:
1316
```swift
14-
import Complex
17+
import ComplexModule
1518

1619
let z = Complex<Double>.i
1720
```
18-
However, there is also a top-level `Numerics` module that simply re-exports the complete public interface of swift-numerics:
21+
22+
There is also a top-level `Numerics` module that re-exports the complete public interface of Swift Numerics:
23+
1924
```swift
2025
import Numerics
2126

22-
// All swift-numerics API is now available
27+
// The entire Swift Numerics API is now available
2328
```
2429

2530
Swift Numerics modules have minimal dependencies on other projects.
31+
2632
The current modules assume only the availability of the Swift and C standard libraries and the runtime support provided by compiler-rt.
27-
Future expansion may assume the availability of other standard interfaces such as [BLAS (Basic Linear Algebra Subprograms)](https://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms) and [LAPACK (Linear Algebra Package)](https://en.wikipedia.org/wiki/LAPACK), but modules with more specialized dependencies (or dependencies that are not available on all platforms supported by Swift) belong in a separate package.
33+
34+
Future expansion may assume the availability of other standard interfaces, such as [BLAS (Basic Linear Algebra Subprograms)](https://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms) and [LAPACK (Linear Algebra Package)](https://en.wikipedia.org/wiki/LAPACK), but modules with more specialized dependencies (or dependencies that are not available on all platforms supported by Swift) belong in a separate package.
2835

2936
Because we intend to make it possible to adopt Swift Numerics modules in the standard library at some future point, Swift Numerics uses the same license and contribution guidelines as the Swift project.
3037

31-
## Process
32-
Swift Numerics is a standalone library separate from the core Swift project.
33-
In practice, it will act as a staging ground for some APIs that may eventually be incorporated into the Swift Standard Library, and when that happens such changes will be proposed to the Swift Standard Library using the established evolution process of the Swift project.
38+
## Using Swift Numerics in your project
39+
40+
To use Swift Numerics in a SwiftPM project:
41+
42+
1. Add the following line to the dependencies in your `Package.swift` file:
43+
44+
```swift
45+
.package(url: "https://github.com/apple/swift-numerics", from: "1.0.0"),
46+
```
47+
48+
2. Add `Numerics` as a dependency for your target:
49+
50+
```swift
51+
.target(name: "MyTarget", dependencies: [
52+
.product(name: "Numerics", package: "swift-numerics"),
53+
"AnotherModule"
54+
]),
55+
```
56+
57+
3. Add `import Numerics` in your source code.
58+
59+
## Source stability
60+
61+
The Swift Numerics package is source stable; version numbers follow [Semantic Versioning](https://semver.org).
62+
The public API of the `swift-numerics` package consists of non-underscored declarations that are marked either `public` or `usableFromInline` in modules re-exported by the top-level `Numerics` module.
63+
Interfaces that aren't part of the public API may continue to change in any release, including patch releases.
64+
65+
Note that contents of the `_NumericsShims` and `_TestSupport` modules, as well as contents of the `Tests` directory, explicitly are not public API.
66+
The definitions therein may therefore change at whim, and the entire module may be removed in any new release.
67+
If you have a use case that requires underscored operations, please raise an issue to request that they be made public API.
68+
69+
Future minor versions of the package may introduce changes to these rules as needed.
70+
71+
We'd like this package to quickly embrace Swift language and toolchain improvements that are relevant to its mandate.
72+
Accordingly, from time to time, we expect that new versions of this package will require clients to upgrade to a more recent Swift toolchain release.
73+
Requiring a new Swift release will only require a minor version bump.
74+
75+
## Contributing to Swift Numerics
76+
77+
Swift Numerics is a standalone library that is separate from the core Swift project, but it will sometimes act as a staging ground for APIs that will later be incorporated into the Swift Standard Library.
78+
When that happens, such changes will be proposed to the Swift Standard Library using the established evolution process of the Swift project.
3479

3580
Swift Numerics uses GitHub issues to track bugs and features. We use pull requests for development.
3681

37-
To propose a new module:
82+
### How to propose a new module
83+
3884
1. Raise an issue with the [new module] tag.
3985
2. Raise a PR with an implementation sketch.
4086
3. Once you have some consensus, ask an admin to create a feature branch against which PRs can be raised.
4187
4. When the design has stabilized and is functional enough to be useful, raise a PR to merge the new module to master.
4288

43-
To propose a new feature for an existing module:
89+
### How to propose a new feature for an existing module
90+
4491
1. Raise an issue with the [enhancement] tag.
4592
2. Raise a PR with your implementation, and discuss the implementation there.
4693
3. Once there is a consensus that the new feature is desirable and the design is suitable, it can be merged.
4794

48-
To fix a bug, or make smaller improvements:
49-
1. Raise a PR with your change. Be sure to add test coverage for whatever changes you are making.
95+
### How to fix a bug, or make smaller improvements
96+
97+
1. Raise a PR with your change.
98+
2. Make sure to add test coverage for whatever changes you are making.
5099

51-
Questions about how to use Swift Numerics modules, or issues that are not clearly bugs can be discussed in the ["Swift Numerics" section of the Swift forums.](https://forums.swift.org/c/related-projects/swift-numerics)
100+
### Forums
101+
102+
Questions about how to use Swift Numerics modules, or issues that are not clearly bugs can be discussed in the ["Swift Numerics" section of the Swift forums](https://forums.swift.org/c/related-projects/swift-numerics).
52103

53104
## Modules
54-
1. [Real](Sources/Real/README.md)
55-
2. [Complex](Sources/Complex/README.md)
105+
106+
1. [`RealModule`](Sources/RealModule/README.md)
107+
2. [`ComplexModule`](Sources/ComplexModule/README.md)
108+
3. [`IntegerUtilities`](Sources/IntegerUtilities/README.md) (on main only, not yet present in a released tag)
56109

57110
## Future expansion
58-
1. [Approximate Equality](https://github.com/apple/swift-numerics/issues/3)
59-
2. [Large Fixed-Width Integers](https://github.com/apple/swift-numerics/issues/4)
60-
3. [Arbitrary-Precision Integers](https://github.com/apple/swift-numerics/issues/5)
61-
4. [Shaped Arrays](https://github.com/apple/swift-numerics/issues/6)
62-
5. [Decimal Floating-point](https://github.com/apple/swift-numerics/issues/7)
63-
6. [Float16](https://github.com/apple/swift-numerics/issues/8)
111+
112+
1. [Large Fixed-Width Integers](https://github.com/apple/swift-numerics/issues/4)
113+
2. [Arbitrary-Precision Integers](https://github.com/apple/swift-numerics/issues/5)
114+
3. [Shaped Arrays](https://github.com/apple/swift-numerics/issues/6)
115+
4. [Decimal Floating-point](https://github.com/apple/swift-numerics/issues/7)
116+
117+
[^1]: The module is named `ComplexModule` instead of `Complex` because Swift is currently unable to use the fully-qualified name for types when a type and module have the same name (discussion here: https://forums.swift.org/t/pitch-fully-qualified-name-syntax/28482).
118+
This would prevent users of Swift Numerics who don't need generic types from doing things such as:
119+
120+
```swift
121+
import Complex
122+
// I know I only ever want Complex<Double>, so I shouldn't need the generic parameter.
123+
typealias Complex = Complex.Complex<Double> // This doesn't work, because name lookup fails.
124+
```
125+
126+
For this reason, modules that would have this ambiguity are suffixed with `Module` within Swift Numerics:
127+
128+
```swift
129+
import ComplexModule
130+
// I know I only ever want Complex<Double>, so I shouldn't need the generic parameter.
131+
typealias Complex = ComplexModule.Complex<Double>
132+
// But I can still refer to the generic type by qualifying the name if I need it occasionally:
133+
let a = ComplexModule.Complex<Float>
134+
```
135+
136+
The `Real` module does not contain a `Real` type, but does contain a `Real` protocol.
137+
Users may want to define their own `Real` type (and possibly re-export the `Real` module)--that is why the suffix is also applied there.
138+
New modules have to evaluate this decision carefully, but can err on the side of adding the suffix.
139+
It's expected that most users will simply `import Numerics`, so this isn't an issue for them.

‎Sources/CMakeLists.txt

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
#[[
2+
This source file is part of the Swift Numerics open source project
3+
4+
Copyright (c) 2019-2021 Apple Inc. and the Swift Numerics project authors
5+
Licensed under Apache License v2.0 with Runtime Library Exception
6+
7+
See https://swift.org/LICENSE.txt for license information
8+
#]]
9+
10+
add_subdirectory(_NumericsShims)
11+
add_subdirectory(ComplexModule)
12+
add_subdirectory(IntegerUtilities)
13+
add_subdirectory(Numerics)
14+
add_subdirectory(RealModule)
15+
if(BUILD_TESTING)
16+
add_subdirectory(_TestSupport)
17+
endif()

0 commit comments

Comments
 (0)