From d349eee4b40ff06583fc88b931de4abd089dd865 Mon Sep 17 00:00:00 2001 From: Reda Lemeden Date: Tue, 22 Nov 2022 15:30:17 +0000 Subject: [PATCH 1/2] First pass at the new Getting Started page --- assets/stylesheets/_pages.scss | 1 + .../stylesheets/pages/_getting-started.scss | 50 +++++ getting-started/_go-further.html | 35 ++++ getting-started/_installing.md | 176 +----------------- getting-started/_use-cases.html | 34 ++++ getting-started/cli-tool/index.md | 6 + getting-started/index.md | 28 +-- getting-started/web-server/index.md | 6 + 8 files changed, 141 insertions(+), 195 deletions(-) create mode 100644 assets/stylesheets/pages/_getting-started.scss create mode 100644 getting-started/_go-further.html create mode 100644 getting-started/_use-cases.html create mode 100644 getting-started/cli-tool/index.md create mode 100644 getting-started/web-server/index.md diff --git a/assets/stylesheets/_pages.scss b/assets/stylesheets/_pages.scss index 61051403f..de7090d7e 100644 --- a/assets/stylesheets/_pages.scss +++ b/assets/stylesheets/_pages.scss @@ -1 +1,2 @@ +@import "pages/getting-started"; @import "pages/swift-evolution"; \ No newline at end of file diff --git a/assets/stylesheets/pages/_getting-started.scss b/assets/stylesheets/pages/_getting-started.scss new file mode 100644 index 000000000..90a12c5fb --- /dev/null +++ b/assets/stylesheets/pages/_getting-started.scss @@ -0,0 +1,50 @@ + +.guide-list { + list-style: none; + padding-left: 0; +} + +.use-case-list { + list-style: none; + padding-left: 0; + display: grid; + gap: 1rem; + + .use-case { + border: 1px solid var(--color-fill-gray); + padding: 0 1rem; + border-radius: 4px; + display: flex; + flex-direction: column; + + h3 { + line-height: 1.4; + font-size: 1.4rem; + } + + p { + flex-grow: 1; + color: var(--color-secondary-label); + } + } + + @media (min-width: 1000px) { + grid-template-columns: repeat(3, 1fr); + } +} + +a.cta-secondary { + border-radius: var(--border-radius); + border: 1px solid var(--color-text); + color: var(--color-text); + display: block; + margin: 1rem 0; + padding: .5rem 0; + text-align: center; + + &:hover { + background-color: var(--color-text); + color: var(--color-fill); + text-decoration: none; + } +} \ No newline at end of file diff --git a/getting-started/_go-further.html b/getting-started/_go-further.html new file mode 100644 index 000000000..435ae85e5 --- /dev/null +++ b/getting-started/_go-further.html @@ -0,0 +1,35 @@ +## Go Further + +Ready to dive deeper? Here are some hand-picked resources covering about various Swift features and use. + + \ No newline at end of file diff --git a/getting-started/_installing.md b/getting-started/_installing.md index 1a0cf2a14..4e642e8f2 100644 --- a/getting-started/_installing.md +++ b/getting-started/_installing.md @@ -1,174 +1,12 @@ ## Installing Swift -The first step to using Swift is to download and install -the compiler and other required components. -Go to the [Download](/download) page -and follow the instructions for your target platform. +If you don't have Swift installed, [install it first](/install). To test that you have Swift installed, run `swift --version` in the terminal. -In order to follow along with the examples below, -make sure to add Swift to your `$PATH`. +### Swift Package Manager -### On macOS +When you install Swift you’ll also get the latest stable version of the Swift build tool and package manager, also known as Swift Package Manager, or SwiftPM . -The default location for the downloadable toolchain on macOS is -`/Library/Developer/Toolchains`. -You can make the latest installed toolchain available for use from the terminal with the following command: - -~~~ shell -$ export TOOLCHAINS=swift -~~~ - -To select any other installed toolchain, use its identifier in the `TOOLCHAINS` -variable. The identifier can be found in toolchain's `Info.plist` file. - -~~~ shell -$ /usr/libexec/PlistBuddy -c "Print CFBundleIdentifier:" /Library/Developer/Toolchains/swift-4.0-RELEASE.xctoolchain/Info.plist -org.swift.4020170919 - -$ export TOOLCHAINS=org.swift.4020170919 -~~~ - -### On Linux - -0. Install required dependencies: - -{% include linux/table.html %} - -If you installed the Swift toolchain on Linux -to a directory other than the system root, -you will need to run the following command, -using the actual path of your Swift installation: - -~~~ shell -$ export PATH=/path/to/Swift/usr/bin:"${PATH}" -~~~ - -### On Windows - -#### Dependencies - -Swift has the following general dependencies: - -- Git (used by Swift Package Manager) - -- Python[^1] (used by the debugger - lldb) - -[^1]: The windows binaries are built against Python 3.10.2 - -Windows has the following additional platform specific dependencies: - -- Windows SDK (provides the Windows headers and import libraries) - -- Visual Studio (provides the Visual C++ SDK/Build Tools for additional headers) - -#### Enabling Developer Mode - -In order to develop applications, particularly with the Swift Package Manager, you will need to enable developer mode. Please see Microsoft's [documentation](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) for instructions for enabling developer mode. - -#### Installation Instructions - -##### Install using the Windows Package Manager - -The [Windows Package Manager](https://docs.microsoft.com/windows/package-manager/) can be found in the [App Store](https://www.microsoft.com/en-us/p/app-installer/9nblggh4nns1) or be [installed directly](ms-appinstaller:?source=https://aka.ms/getwinget). - -0. Install required dependencies: - - The platform dependencies cannot be installed through the Windows Package Manager as the install rules do not install the components necessary. They will be installed through Visual Studio installer. - - ~~~ cmd - winget install Git.Git - winget install Python.Python.3 --version 3.10.2150.0 - - curl -sOL https://aka.ms/vs/16/release/vs_community.exe - start /w vs_community.exe --passive --wait --norestart --nocache ^ - --installPath "%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Community" ^ - --add Microsoft.VisualStudio.Component.Windows10SDK.19041 ^ - --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 - del /q vs_community.exe - ~~~ - - Start up a new Command Prompt and install the Python library six. - - ~~~ cmd - pip install six - ~~~ - -0. Install Swift: - - Swift can be installed through the official installer directly, or using the Windows Package Manager as well. Notice that Windows Package Manager release may be behind the official release. - - * Using the official installer: - 1. Download the [latest package release](/download). - 1. Run the package installer. - - * Using the Windows Package Manager: - ~~~ cmd - winget install Swift.Toolchain - ~~~ - -A Swift toolchain will be installed at `%SystemDrive%\Library\Developer\Toolchains\unknown-Asserts-development.xctoolchain`. A compatible Swift SDK will be installed at `%SystemDrive%\Library\Developer\Platforms\Windows.platform\Developer\SDKs\Windows.sdk`. - -##### Traditional Installation - -> **NOTE:** The traditional installation process is required for Swift older than 5.4.2. - -Swift has been tested with [Visual Studio 2019](https://visualstudio.microsoft.com). You will need to install Visual Studio with the following components. The installer for Swift is available in the [Download](/download) section. The toolchain on Windows is installed to `%SystemDrive%\Library\Developer\Toolchains`. - -The following Visual Studio components are **required**: - -| Component | Visual Studio ID | -|-----------|------------------| -| MSVC v142 - VS 2019 C++ x64/x86 build tools (Latest) | Microsoft.VisualStudio.Component.VC.Tools.x86.x64 | -| Windows 10 SDK (10.0.17763.0)[^2] | Microsoft.VisualStudio.Component.Windows10SDK.17763 | - -[^2]: You may install a newer SDK instead. - -The following additional Visual Studio components are **recommended**: - -| Component | Visual Studio ID | -|-----------|------------------| -| Git for Windows | Microsoft.VisualStudio.Component.Git | -| Python 3 64-bit (3.7.8) | Component.CPython.x64 | - -The following additional Visual Studio component is **suggested**: - -| Component | Visual Studio ID | -|-----------|------------------| -| C++ CMake tools for Windows | Microsoft.VisualStudio.Component.VC.CMake.Project | - -##### Support Files - -> **NOTE:** This is only required for versions older than 5.4.2 - -You must use the `x64 Native Tools for VS2019 Command Prompt` to run the following steps. The `x64 Native Tools for VS2019 Command Prompt` runs the `DevEnv` script from Visual Studio that sets up the necessary environment variables to find the system headers. - -In order to make the Windows SDK accessible to Swift, it is necessary to deploy a few files into the Windows SDK. The following will modify your Visual Studio Installation, and as such will require to be run from an (elevated) "Administrator" `x86 Native Tools for VS2019 Command Prompt`. - -~~~ cmd -copy /Y %SDKROOT%\usr\share\ucrt.modulemap "%UniversalCRTSdkDir%\Include\%UCRTVersion%\ucrt\module.modulemap" -copy /Y %SDKROOT%\usr\share\visualc.modulemap "%VCToolsInstallDir%\include\module.modulemap" -copy /Y %SDKROOT%\usr\share\visualc.apinotes "%VCToolsInstallDir%\include\visualc.apinotes" -copy /Y %SDKROOT%\usr\share\winsdk.modulemap "%UniversalCRTSdkDir%\Include\%UCRTVersion%\um\module.modulemap" -~~~ - -Because it is installing the files into the Visual Studio image, the files will need to be copied each time Visual Studio is updated. - -##### Repairing after Visual Studio Updates - -If Visual Studio is updated, you may have to repair the installation. See Microsoft's [instructions](https://support.microsoft.com/en-us/windows/repair-apps-and-programs-in-windows-10-e90eefe4-d0a2-7c1b-dd59-949a9030f317) for repairing installed programs. - -* * * - -### Swift Version - -You can verify that you are running the expected version of Swift -by entering the `swift` command and passing the `--version` flag: - -~~~ shell -$ swift --version -Apple Swift version 2.2-dev (LLVM ..., Clang ..., Swift ...) -~~~ - -The `-dev` suffix on the version number -is used to indicate that it's a *development* build, -not a released version. +SwiftPM does lots of things: +- Build your project with `swift build`. +- Test your project with `swift test`. +- Run your project with `swift run`. diff --git a/getting-started/_use-cases.html b/getting-started/_use-cases.html new file mode 100644 index 000000000..c90a126bd --- /dev/null +++ b/getting-started/_use-cases.html @@ -0,0 +1,34 @@ +## Using Swift + +Below are some examples of the many use cases of Swift. + + \ No newline at end of file diff --git a/getting-started/cli-tool/index.md b/getting-started/cli-tool/index.md new file mode 100644 index 000000000..9dfafa783 --- /dev/null +++ b/getting-started/cli-tool/index.md @@ -0,0 +1,6 @@ +--- +layout: page +title: Build a Command-line Tool +--- + +TODO \ No newline at end of file diff --git a/getting-started/index.md b/getting-started/index.md index 48292b0dd..02de44e07 100644 --- a/getting-started/index.md +++ b/getting-started/index.md @@ -3,30 +3,6 @@ layout: page title: Getting Started --- -Here, you’ll find information about the how to use the Swift programming language. - -If you're new to Swift, check out [A Swift Tour][TSPL] in -_The Swift Programming Language_, for a quick introduction to the -most important concepts and features of the language. - -[TSPL]: https://developer.apple.com/library/prerelease/content/documentation/Swift/Conceptual/Swift_Programming_Language/GuidedTour.html#//apple_ref/doc/uid/TP40014097-CH2-ID1 - {% include_relative _installing.md %} -{% include_relative _repl.md %} -{% comment %}{% include_relative _swiftc.md %}{% endcomment %} -{% include_relative _build-system.md %} -{% comment %}{% include_relative _reference-documentation.md %}{% endcomment %} -{% include_relative _lldb.md %} -{% comment %}{% include_relative _core-libraries.md %}{% endcomment %} - -* * * - -Now that you've been introduced to the Swift REPL, build system, and debugger, -here are a few suggestions for what to do next: - -- Check out the [Package Manager project page](/package-manager) - for a deep dive into the Swift build system and package manager. -- Read [Contributing to Swift](/contributing) - to learn about the different ways you can participate in the Swift community. -- Go to [developer.apple.com/swift](https://developer.apple.com/swift/resources/) - for additional Swift resources, including videos, sample code, and playgrounds. +{% include_relative _use-cases.html %} +{% include_relative _go-further.html %} \ No newline at end of file diff --git a/getting-started/web-server/index.md b/getting-started/web-server/index.md new file mode 100644 index 000000000..bf46db848 --- /dev/null +++ b/getting-started/web-server/index.md @@ -0,0 +1,6 @@ +--- +layout: page +title: Build a Web Server +--- + +TODO \ No newline at end of file From 7943eceb18f6f907dc25f31562e778103998d337 Mon Sep 17 00:00:00 2001 From: Reda Lemeden Date: Tue, 20 Dec 2022 17:08:35 +0100 Subject: [PATCH 2/2] Update vapor guide path --- getting-started/_use-cases.html | 2 +- getting-started/{web-server => vapor-web-server}/index.md | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename getting-started/{web-server => vapor-web-server}/index.md (100%) diff --git a/getting-started/_use-cases.html b/getting-started/_use-cases.html index c90a126bd..f07832daf 100644 --- a/getting-started/_use-cases.html +++ b/getting-started/_use-cases.html @@ -10,7 +10,7 @@

Build a Web Server (Vapor)

Requires macOS or Linux.

- Start tutorial + Start tutorial
  • diff --git a/getting-started/web-server/index.md b/getting-started/vapor-web-server/index.md similarity index 100% rename from getting-started/web-server/index.md rename to getting-started/vapor-web-server/index.md