From a3c7a0b025e07f39c8aebb7a6f8ba079e17e6d0e Mon Sep 17 00:00:00 2001 From: Lucian Radu Teodorescu Date: Fri, 20 Dec 2024 13:56:31 +0200 Subject: [PATCH 1/4] Start a compiler troubleshooting guide. --- Docs/Compiler/Troubleshooting.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 Docs/Compiler/Troubleshooting.md diff --git a/Docs/Compiler/Troubleshooting.md b/Docs/Compiler/Troubleshooting.md new file mode 100644 index 000000000..1b2e3ef85 --- /dev/null +++ b/Docs/Compiler/Troubleshooting.md @@ -0,0 +1,29 @@ +# Troubleshooting compiler build issues + +## Some of my CI builds succeed, and some fail. + +At this point, Hylo compiler uses both a build system based on CMake, and one based on `swift build`. +Investigate if just one of them fails, and take it from there. + +## Updating an external library + +Let's take the example of Swifty-LLVM, which is a Hylo repository for which we always get the latest version from `main`. +For this example, making a change to Swifty-LLVM should be picked up automatically, after the change is submitted to `main`. +But this doesn't always happen. + +To properly update the external library, do the following: +- quit any IDEs (yes, please do that) +- delete the build folder (e.g., `.build`) +- delete `Package.resolved` +- run `swift package resolve` +- build with Swift build system (e.g., `swift build -c release`), and ensure everything builds +- build with the CMake system and ensure that everything builds +- upload the changes to `Package.resolved`; this should contain the commit sha for the latest version of the library. + +> **_NOTE:_** +> VS Code imediatelly re-generates the swift packages, so, depending on the order of operations, this may interfere with the actual resolving of the packages. +> This is why we recommend closing the IDE first. + +> **_NOTE:_** +> This will most probably update other packages that swift will use. +> This is expected. \ No newline at end of file From 68945db7db63f98360f5aa6f794fb197e744f168 Mon Sep 17 00:00:00 2001 From: Lucian Radu Teodorescu Date: Thu, 2 Jan 2025 11:21:17 +0200 Subject: [PATCH 2/4] Minor fixes. --- Docs/Compiler/Troubleshooting.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Docs/Compiler/Troubleshooting.md b/Docs/Compiler/Troubleshooting.md index 1b2e3ef85..868d2d08a 100644 --- a/Docs/Compiler/Troubleshooting.md +++ b/Docs/Compiler/Troubleshooting.md @@ -15,7 +15,6 @@ To properly update the external library, do the following: - quit any IDEs (yes, please do that) - delete the build folder (e.g., `.build`) - delete `Package.resolved` -- run `swift package resolve` - build with Swift build system (e.g., `swift build -c release`), and ensure everything builds - build with the CMake system and ensure that everything builds - upload the changes to `Package.resolved`; this should contain the commit sha for the latest version of the library. @@ -25,5 +24,5 @@ To properly update the external library, do the following: > This is why we recommend closing the IDE first. > **_NOTE:_** -> This will most probably update other packages that swift will use. +> This will most probably update other packages that swift will use (unrelated content in `Package.resolved` is changed). > This is expected. \ No newline at end of file From 1c3f48e3dc8a881f888b1915d5578b76ce03bd9e Mon Sep 17 00:00:00 2001 From: Lucian Radu Teodorescu Date: Thu, 2 Jan 2025 11:28:48 +0200 Subject: [PATCH 3/4] More clarifications. --- Docs/Compiler/Troubleshooting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Docs/Compiler/Troubleshooting.md b/Docs/Compiler/Troubleshooting.md index 868d2d08a..9b2b1d4ad 100644 --- a/Docs/Compiler/Troubleshooting.md +++ b/Docs/Compiler/Troubleshooting.md @@ -8,8 +8,8 @@ Investigate if just one of them fails, and take it from there. ## Updating an external library Let's take the example of Swifty-LLVM, which is a Hylo repository for which we always get the latest version from `main`. -For this example, making a change to Swifty-LLVM should be picked up automatically, after the change is submitted to `main`. -But this doesn't always happen. +For this example, making a change to Swifty-LLVM should be picked up automatically by the CMake build, after the change is submitted to `main`. +But this doesn't happen with the native swift build system. To properly update the external library, do the following: - quit any IDEs (yes, please do that) From d58545845953cb1d5c163fda635fdd36ed2d2b7d Mon Sep 17 00:00:00 2001 From: Lucian Radu Teodorescu Date: Tue, 4 Feb 2025 15:21:44 +0200 Subject: [PATCH 4/4] Change from "troubleshooting guide" into "HOWTOs" Also update the text with more concrete steps. --- Docs/Compiler/Troubleshooting.md | 37 +++++++++++--------------------- 1 file changed, 12 insertions(+), 25 deletions(-) diff --git a/Docs/Compiler/Troubleshooting.md b/Docs/Compiler/Troubleshooting.md index 9b2b1d4ad..5cd386e8e 100644 --- a/Docs/Compiler/Troubleshooting.md +++ b/Docs/Compiler/Troubleshooting.md @@ -1,28 +1,15 @@ -# Troubleshooting compiler build issues - -## Some of my CI builds succeed, and some fail. - -At this point, Hylo compiler uses both a build system based on CMake, and one based on `swift build`. -Investigate if just one of them fails, and take it from there. +# HOWTOs ## Updating an external library -Let's take the example of Swifty-LLVM, which is a Hylo repository for which we always get the latest version from `main`. -For this example, making a change to Swifty-LLVM should be picked up automatically by the CMake build, after the change is submitted to `main`. -But this doesn't happen with the native swift build system. - -To properly update the external library, do the following: -- quit any IDEs (yes, please do that) -- delete the build folder (e.g., `.build`) -- delete `Package.resolved` -- build with Swift build system (e.g., `swift build -c release`), and ensure everything builds -- build with the CMake system and ensure that everything builds -- upload the changes to `Package.resolved`; this should contain the commit sha for the latest version of the library. - -> **_NOTE:_** -> VS Code imediatelly re-generates the swift packages, so, depending on the order of operations, this may interfere with the actual resolving of the packages. -> This is why we recommend closing the IDE first. - -> **_NOTE:_** -> This will most probably update other packages that swift will use (unrelated content in `Package.resolved` is changed). -> This is expected. \ No newline at end of file +We use Swifty-LLVM as an example of external library that needs to be updated. +We assume that there is a change on the `main` branch of Swifty-LLVM that should be used by Hylo compiler. + +Steps: +- In [`CMakeModules` repository](https://github.com/hylo-lang/CMakeModules): + - in the corresponding `FindXXX.cmake` file (e.g., `FindSwifty-LLVM.cmake`) edit the `GIT_TAG` value to point to the SHA of the commit that should be included in Hylo; + - create a PR with the changes, and ensure it's merged. +- In `hylo` repository: + - in `TopLevelDefaults.cmake`, change the `GIT_TAG` value corresponding to `CMakeModules` repository to point to the SHA containing the change above; + - run `swift package update XXX`, where `XXX` is the name of the package that needs to be updated (`Swift-LLVM` in our example); this will update `Package.resolved` file, with the SHA of the change that needs to be brought in; + - double check that the SHA in `Package.resolved` matches the one that was written in the `CMakeModules` repository;