diff --git a/README.md b/README.md index 00a259d227..f075b5d0c7 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,7 @@ If you find any bugs or have any suggestion for improvement, please > [!TIP] > For building the client on macOS we have a tool called `mac-crafter`. > You will find more information about it in [its dedicated README](admin/osx/mac-crafter/README.md). +> Also, please note the [README in the NextcloudIntegration project](shell_integration/MacOSX/NextcloudIntegration/README.md) which provides an even more convenient way to work on and build the desktop client on macOS by using Xcode. #### 1. 🚀 Set up your local development environment diff --git a/REUSE.toml b/REUSE.toml index af22bcd74b..95e5190405 100644 --- a/REUSE.toml +++ b/REUSE.toml @@ -42,7 +42,15 @@ SPDX-FileCopyrightText = "2014 ownCloud GmbH, 2022 Nextcloud GmbH and Nextcloud SPDX-License-Identifier = "GPL-2.0-or-later" [[annotations]] -path = ["shell_integration/MacOSX/NextcloudIntegration/NextcloudIntegration.xcodeproj/project.pbxproj", "shell_integration/MacOSX/NextcloudIntegration/NextcloudIntegration.xcodeproj/project.xcworkspace/contents.xcworkspacedata", "shell_integration/MacOSX/NextcloudIntegration/NextcloudIntegration.xcodeproj/project.xcworkspace/xcshareddata/IDEWorkspaceChecks.plist", "shell_integration/MacOSX/NextcloudIntegration/NextcloudIntegration.xcodeproj/xcshareddata/xcschemes/FinderSyncExt.xcscheme"] +path = [ + "shell_integration/MacOSX/NextcloudIntegration/.gitignore", + "shell_integration/MacOSX/NextcloudIntegration/NextcloudIntegration.xcodeproj/project.pbxproj", + "shell_integration/MacOSX/NextcloudIntegration/NextcloudIntegration.xcodeproj/project.xcworkspace/contents.xcworkspacedata", + "shell_integration/MacOSX/NextcloudIntegration/NextcloudIntegration.xcodeproj/project.xcworkspace/xcshareddata/IDEWorkspaceChecks.plist", + "shell_integration/MacOSX/NextcloudIntegration/NextcloudIntegration.xcodeproj/xcshareddata/xcschemes/FinderSyncExt.xcscheme", + "shell_integration/MacOSX/NextcloudIntegration/NextcloudIntegration.xcodeproj/xcshareddata/xcschemes/NextcloudDev.xcscheme", + "shell_integration/MacOSX/NextcloudIntegration/README.md" +] precedence = "aggregate" SPDX-FileCopyrightText = "2025 Nextcloud GmbH and Nextcloud contributors" SPDX-License-Identifier = "GPL-2.0-or-later" diff --git a/shell_integration/MacOSX/NextcloudIntegration/NextcloudDev/Craft.sh b/shell_integration/MacOSX/NextcloudIntegration/NextcloudDev/Craft.sh new file mode 100644 index 0000000000..beecc3f89a --- /dev/null +++ b/shell_integration/MacOSX/NextcloudIntegration/NextcloudDev/Craft.sh @@ -0,0 +1,40 @@ +#!/bin/env zsh + +# SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors +# SPDX-License-Identifier: GPL-2.0-or-later + +# Read the available environment paths which include (for example) Homebrew. +for f in /etc/paths.d/*; do + while read -r line; do + export PATH="$PATH:$line" + done < "$f" +done + +if [ -f "~/.zprofile" ]; then + echo "Sourcing ~/.zprofile to include possible PATH definitions..." + source "~/.zprofile" +fi + +if [ -z "${CODE_SIGN_IDENTITY}" ]; then + echo "Error: CODE_SIGN_IDENTITY is not defined or is empty!" + exit 1 +fi + +DESKTOP_CLIENT_PROJECT_ROOT="$SOURCE_ROOT/../../.." + +if [ -d "$DESKTOP_CLIENT_PROJECT_ROOT/admin/osx/mac-crafter" ]; then + cd "$DESKTOP_CLIENT_PROJECT_ROOT/admin/osx/mac-crafter" +else + echo "Error: Directory '$DESKTOP_CLIENT_PROJECT_ROOT/admin/osx/mac-crafter' does not exist!" + exit 1 +fi + +swift run mac-crafter \ + --build-path="$DERIVED_SOURCES_DIR" \ + --product-path="/Applications" \ + --build-type="Debug" \ + --dev \ + --disable-auto-updater \ + --build-file-provider-module \ + --code-sign-identity="$CODE_SIGN_IDENTITY" \ + "$DESKTOP_CLIENT_PROJECT_ROOT" diff --git a/shell_integration/MacOSX/NextcloudIntegration/NextcloudIntegration.xcodeproj/project.pbxproj b/shell_integration/MacOSX/NextcloudIntegration/NextcloudIntegration.xcodeproj/project.pbxproj index 0cfcbb5dfa..9343b005e7 100644 --- a/shell_integration/MacOSX/NextcloudIntegration/NextcloudIntegration.xcodeproj/project.pbxproj +++ b/shell_integration/MacOSX/NextcloudIntegration/NextcloudIntegration.xcodeproj/project.pbxproj @@ -196,9 +196,13 @@ 53FE14642B8F6700006C4193 /* ShareViewDataSourceUIDelegate.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ShareViewDataSourceUIDelegate.swift; sourceTree = ""; }; 53FE14662B8F78B6006C4193 /* ShareOptionsView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ShareOptionsView.swift; sourceTree = ""; }; AA02B2AA2E7048C600C72B34 /* Keychain.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Keychain.swift; sourceTree = ""; }; + AA0A6B1D2E8EA94F007F4A7A /* Craft.sh */ = {isa = PBXFileReference; lastKnownFileType = text.script.sh; path = Craft.sh; sourceTree = ""; }; + AA1191B52E8EAFF900E21C7B /* Build.xcconfig.template */ = {isa = PBXFileReference; lastKnownFileType = text; path = Build.xcconfig.template; sourceTree = ""; }; + AA27A4E32E93C0D700665051 /* README.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = README.md; sourceTree = ""; }; AA7F17E02E7017230000E928 /* Authentication.storyboard */ = {isa = PBXFileReference; lastKnownFileType = file.storyboard; path = Authentication.storyboard; sourceTree = ""; }; AA7F17E22E70173E0000E928 /* AuthenticationViewController.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AuthenticationViewController.swift; sourceTree = ""; }; AA7F17E62E7038340000E928 /* NSError+FileProviderErrorCode.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "NSError+FileProviderErrorCode.swift"; sourceTree = ""; }; + AA826BEE2E8EAA7500CE49C4 /* Build.xcconfig */ = {isa = PBXFileReference; lastKnownFileType = text.xcconfig; path = Build.xcconfig; sourceTree = ""; }; AA9987852E72B6DB00B2C428 /* NextcloudKit+clearAccountErrorState.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "NextcloudKit+clearAccountErrorState.swift"; sourceTree = ""; }; AAA69D922E3BB09900BBD44D /* Localizable.xcstrings */ = {isa = PBXFileReference; lastKnownFileType = text.json.xcstrings; path = Localizable.xcstrings; sourceTree = ""; }; AAC00D292E37B29D006010FE /* Localizable.xcstrings */ = {isa = PBXFileReference; lastKnownFileType = text.json.xcstrings; path = Localizable.xcstrings; sourceTree = ""; }; @@ -373,6 +377,16 @@ path = FileProviderUIExt; sourceTree = ""; }; + AA0A6B1C2E8EA948007F4A7A /* NextcloudDev */ = { + isa = PBXGroup; + children = ( + AA826BEE2E8EAA7500CE49C4 /* Build.xcconfig */, + AA1191B52E8EAFF900E21C7B /* Build.xcconfig.template */, + AA0A6B1D2E8EA94F007F4A7A /* Craft.sh */, + ); + path = NextcloudDev; + sourceTree = ""; + }; AA7F17DF2E70171A0000E928 /* Authentication */ = { isa = PBXGroup; children = ( @@ -385,7 +399,9 @@ C2B573941B1CD88000303B36 = { isa = PBXGroup; children = ( + AA27A4E32E93C0D700665051 /* README.md */, C2B573B31B1CD91E00303B36 /* desktopclient */, + AA0A6B1C2E8EA948007F4A7A /* NextcloudDev */, C2B573D81B1CD9CE00303B36 /* FinderSyncExt */, 538E396B27F4765000FA63D5 /* FileProviderExt */, 53B9797F2B84C81F002DA742 /* FileProviderUIExt */, @@ -466,6 +482,25 @@ }; /* End PBXHeadersBuildPhase section */ +/* Begin PBXLegacyTarget section */ + AA0A62F22E8EA929007F4A7A /* NextcloudDev */ = { + isa = PBXLegacyTarget; + buildArgumentsString = "\"$(SOURCE_ROOT)/NextcloudDev/Craft.sh\""; + buildConfigurationList = AA0A62F52E8EA929007F4A7A /* Build configuration list for PBXLegacyTarget "NextcloudDev" */; + buildPhases = ( + ); + buildToolPath = /bin/zsh; + buildWorkingDirectory = ""; + dependencies = ( + ); + name = NextcloudDev; + packageProductDependencies = ( + ); + passBuildSettingsInEnvironment = 1; + productName = NextcloudDev; + }; +/* End PBXLegacyTarget section */ + /* Begin PBXNativeTarget section */ 538E396627F4765000FA63D5 /* FileProviderExt */ = { isa = PBXNativeTarget; @@ -593,6 +628,9 @@ 53B9797D2B84C81F002DA742 = { CreatedOnToolsVersion = 15.2; }; + AA0A62F22E8EA929007F4A7A = { + CreatedOnToolsVersion = 26.0.1; + }; C2B573B01B1CD91E00303B36 = { CreatedOnToolsVersion = 6.3.1; DevelopmentTeam = 9B5WD74GWJ; @@ -739,6 +777,7 @@ 538E396627F4765000FA63D5 /* FileProviderExt */, 53B9797D2B84C81F002DA742 /* FileProviderUIExt */, 53903D0B2956164F00D0B308 /* NCDesktopClientSocketKit */, + AA0A62F22E8EA929007F4A7A /* NextcloudDev */, ); }; /* End PBXProject section */ @@ -1267,6 +1306,80 @@ }; name = Release; }; + AA0A62F32E8EA929007F4A7A /* Debug */ = { + isa = XCBuildConfiguration; + baseConfigurationReference = AA826BEE2E8EAA7500CE49C4 /* Build.xcconfig */; + buildSettings = { + ALWAYS_SEARCH_USER_PATHS = NO; + ASSETCATALOG_COMPILER_GENERATE_SWIFT_ASSET_SYMBOL_EXTENSIONS = YES; + CLANG_ANALYZER_NONNULL = YES; + CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE; + CLANG_CXX_LANGUAGE_STANDARD = "gnu++20"; + CLANG_ENABLE_MODULES = YES; + CLANG_ENABLE_OBJC_ARC = YES; + CLANG_ENABLE_OBJC_WEAK = YES; + CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR; + CLANG_WARN_DOCUMENTATION_COMMENTS = YES; + CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR; + CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE; + CODE_SIGN_STYLE = Automatic; + COPY_PHASE_STRIP = NO; + DEBUGGING_SYMBOLS = YES; + DEBUG_INFORMATION_FORMAT = dwarf; + ENABLE_USER_SCRIPT_SANDBOXING = YES; + GCC_C_LANGUAGE_STANDARD = gnu17; + GCC_DYNAMIC_NO_PIC = NO; + GCC_GENERATE_DEBUGGING_SYMBOLS = YES; + GCC_OPTIMIZATION_LEVEL = 0; + GCC_PREPROCESSOR_DEFINITIONS = ( + "DEBUG=1", + "$(inherited)", + ); + GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR; + GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE; + LOCALIZATION_PREFERS_STRING_CATALOGS = YES; + MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE; + MTL_FAST_MATH = YES; + ONLY_ACTIVE_ARCH = YES; + OTHER_CFLAGS = ""; + OTHER_LDFLAGS = ""; + PRODUCT_NAME = "$(TARGET_NAME)"; + }; + name = Debug; + }; + AA0A62F42E8EA929007F4A7A /* Release */ = { + isa = XCBuildConfiguration; + baseConfigurationReference = AA826BEE2E8EAA7500CE49C4 /* Build.xcconfig */; + buildSettings = { + ALWAYS_SEARCH_USER_PATHS = NO; + ASSETCATALOG_COMPILER_GENERATE_SWIFT_ASSET_SYMBOL_EXTENSIONS = YES; + CLANG_ANALYZER_NONNULL = YES; + CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE; + CLANG_CXX_LANGUAGE_STANDARD = "gnu++20"; + CLANG_ENABLE_MODULES = YES; + CLANG_ENABLE_OBJC_ARC = YES; + CLANG_ENABLE_OBJC_WEAK = YES; + CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR; + CLANG_WARN_DOCUMENTATION_COMMENTS = YES; + CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR; + CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE; + CODE_SIGN_STYLE = Automatic; + COPY_PHASE_STRIP = NO; + DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym"; + ENABLE_NS_ASSERTIONS = NO; + ENABLE_USER_SCRIPT_SANDBOXING = YES; + GCC_C_LANGUAGE_STANDARD = gnu17; + GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR; + GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE; + LOCALIZATION_PREFERS_STRING_CATALOGS = YES; + MTL_ENABLE_DEBUG_INFO = NO; + MTL_FAST_MATH = YES; + OTHER_CFLAGS = ""; + OTHER_LDFLAGS = ""; + PRODUCT_NAME = "$(TARGET_NAME)"; + }; + name = Release; + }; C2B573991B1CD88000303B36 /* Debug */ = { isa = XCBuildConfiguration; buildSettings = { @@ -1584,6 +1697,15 @@ defaultConfigurationIsVisible = 0; defaultConfigurationName = Release; }; + AA0A62F52E8EA929007F4A7A /* Build configuration list for PBXLegacyTarget "NextcloudDev" */ = { + isa = XCConfigurationList; + buildConfigurations = ( + AA0A62F32E8EA929007F4A7A /* Debug */, + AA0A62F42E8EA929007F4A7A /* Release */, + ); + defaultConfigurationIsVisible = 0; + defaultConfigurationName = Release; + }; C2B573981B1CD88000303B36 /* Build configuration list for PBXProject "NextcloudIntegration" */ = { isa = XCConfigurationList; buildConfigurations = ( diff --git a/shell_integration/MacOSX/NextcloudIntegration/NextcloudIntegration.xcodeproj/xcshareddata/xcschemes/NextcloudDev.xcscheme b/shell_integration/MacOSX/NextcloudIntegration/NextcloudIntegration.xcodeproj/xcshareddata/xcschemes/NextcloudDev.xcscheme new file mode 100644 index 0000000000..19e87d61f6 --- /dev/null +++ b/shell_integration/MacOSX/NextcloudIntegration/NextcloudIntegration.xcodeproj/xcshareddata/xcschemes/NextcloudDev.xcscheme @@ -0,0 +1,72 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/shell_integration/MacOSX/NextcloudIntegration/README.md b/shell_integration/MacOSX/NextcloudIntegration/README.md new file mode 100644 index 0000000000..a8050d854c --- /dev/null +++ b/shell_integration/MacOSX/NextcloudIntegration/README.md @@ -0,0 +1,73 @@ +# Nextcloud macOS Integration Project + +This is an Xcode project to build platform-specific components for the Nextcloud desktop client. +As an example, this includes the file provider extension. + +## Nextcloud Developer Build + +There is a special target in the Xcode project which integrates the `mac-crafter` command-line tool as an external build system in form of a scheme. +In other words: The "NextcloudDev" scheme enables you to build, run and debug the Nextcloud desktop client with the simple run action in Xcode. + +### Requirements + +- You must have an Apple Development certificate for signing in your keychain. + +### Usage + +1. Copy [`Build.xcconfig.template`](NextcloudDev/Build.xcconfig.template) in the "NextcloudDev" source code folder to `Build.xcconfig` in the same location and adjust the values in it to your local setup. +2. Build or run the "NextcloudDev scheme". + +### Known Issues + +- Right now, the project does not support signing a different app identity than the default one (`com.nextcloud.desktopclient`) which is owned by the Nextcloud GmbH development team registered with Apple. + This means that you have to be signed in with a developer account in Xcode which is part of that development team when building. +- Even when building successfully, Xcode may conclude that the build failed or at least some errors occurred during the build. + During the build, some command outputs messages with an "Error: " prefix. + Since this is the same way the compiler usually reports errors to Xcode, the latter assumes something might have gone wrong. + But no invocation exits with an error code. + Hence, the build can still complete successfully while Xcode might just misinterpret the console output. + You will see at the end of the build output log in Xcode. + +### How It Works + +- The "NextcloudDev" target runs the [Craft.sh](NextcloudDev/Craft.sh) shell script which is part of this Xcode project. +- `Craft.sh` prepares the execution of and finally runs [`mac-crafter`](https://github.com/nextcloud/desktop/tree/master/admin/osx/mac-crafter) which is part of the Nextcloud desktop client repository to simplify builds on macOS. +- By running `mac-crafter` with the right arguments and options, Xcode can attach to the built app with its debugger and stop at breakpoints. + One of the key factors is the `Debug` build type which flips certain switches in the CMake build scripts ([in example: app hardening or get-task-allow entitlement](https://github.com/nextcloud/desktop/pull/8474/files)). +- The built Nextcloud desktop client app bundle is not placed into a derived data directory of Xcode but `/Applications`. + The standard behavior of placing the product into Xcode's derived data directory would result in absolute reference paths within the scheme file which are not portable across devices and users due to varying user names. + +### Hints + +Just for reference, a few helpful snippets for inspecting state on breakpoints with the Xcode debugger. + +#### Print a `QString` + +```lldb +call someString.toStdString() +``` + +#### Print a `QStringList` + +```lldb +call someStrings.join("\n").toStdString() +``` + +#### Attach to File Provider Extension Process + +You can debug the file provider extension process(es) in Xcode by attaching to them by their binary name. + +1. Select this menu item in Xcode: _Debug_ → _Attach to Process by PID or Name..._ +2. Enter `FileProviderExt`. + If you would also like to debug the file provider UI extension, then you can additionally specify `FileProviderUIExt`. +3. Confirm. +4. If no process is already running, then Xcode will wait for it to be launched to attach automatically. + This usually happens when you launch the main app or set up a new account with file provider enabled. + +#### Work on NextcloudFileProviderKit and NextcloudKit + +You can directly debug changes to these dependencies edited from this project. +You have to have local repository clones of the packages somewhere locally, though. +Drag and drop the package folders into the project navigator of the NextcloudIntegration project. +This will cause Xcode to resolve to the local and editable package instead of a cached read-only clone from GitHub. +When you then run the build action of this root project, the local dependency is built as well.