## 1. Project Overview & Quickstart (iterate-ch/cyberduck)

# Cyberduck

[](https://github.com/iterate-ch/cyberduck/commits/master)
[](https://raw.githubusercontent.com/iterate-ch/cyberduck/master/LICENSE)
[](https://github.com/iterate-ch/cyberduck/actions)
[](https://fosstodon.org/@cyberduck)
[](https://gurubase.io/g/cyberduck)

This is the development home for Cyberduck, a libre file transfer client for macOS and Windows. Command line interface (CLI) for Linux, macOS and Windows. The core libraries are used in [Mountain Duck](https://mountainduck.io/).



## Mailing Lists

There is a [Google Groups Cyberduck](http://groups.google.com/group/cyberduck/) discussion mailing list.

The following additional [mailing lists](http://lists.cyberduck.io/) are hosted:

* [News](http://lists.cyberduck.io/mailman/listinfo/cyberduck-news) Announcements of new releases
* [Localization](http://lists.cyberduck.io/mailman/listinfo/cyberduck-localization) Notifications about changes to the translations needed

## Source

Source code is available licensed under the [GNU General Public License Version 3](https://www.gnu.org/licenses/gpl-3.0.en.html). Pull requests welcome!

## Localizations

Translations to new languages are welcome. We use [Transifex](https://app.transifex.com/cyberduck/cyberduck/dashboard/)
to localize resources. Current available localizations are _English_, _Czech_, _Dutch_, _Finnish_, _French_, _German_,
_Italian_, _Japanese_, _Korean_, _Norwegian_, _Portuguese_, _Slovak_, _Spanish_, _Chinese (Traditional & Simplified
Han)_, _Russian_, _Swedish_, _Hungarian_, _Danish_, _Polish_, _Indonesian_, _Catalan_, _Welsh_, _Thai_, _Turkish_,
_Hebrew_, _Latvian_, _Greek_, _Serbian_, _Georgian_ and _Slovenian_.

Make sure to subscribe to the [localization mailing list](http://lists.cyberduck.ch/mailman/listinfo/cyberduck-localization).

## Documentation

For general help about using Cyberduck, please refer to the [documentation](https://docs.cyberduck.io). The documentation is maintained in its own [repository](https://github.com/iterate-ch/docs).

## Additional Connection Profiles

Additional connection profiles not bundled by default but available in _Preferences → Profiles_ are maintained in its own [repository](https://github.com/iterate-ch/profiles).

## Snapshot and Beta builds

These are nightly snapshot builds from the current development trunk featuring the latest bug fixes and enhancements. Be
warned, though, these builds are potentially unstable and experimental. You can also switch to beta or snapshot builds
in _Preferences → Update_.

## Prerequisites

- Java 11 SDK or later
- Apache Ant 1.10.1 or later
- Apache Maven 3.5 or later

### macOS

- [Xcode 12](https://developer.apple.com/xcode/download/) or later

### Windows

#### Installation

**Manually**
- Visual Studio 2022, following workloads are required:
  - `.NET desktop development`
  - `Universal Windows Platform development`
  - `Desktop development with C++`
- [Bonjour SDK for Windows](https://support.apple.com/kb/dl999)
- [Wix v3](https://wixtoolset.org/docs/wix3/) (Optional)

**Chocolatey**

_Without Visual Studio (IDE)_
```sh
choco install visualstudio2022buildtools -y
choco install visualstudio2022-workload-manageddesktopbuildtools -y
choco install visualstudio2022-workload-vctools -y
choco install visualstudio2022-workload-universalbuildtools -y
```

_With Visual Studio IDE_
```sh
choco install visualstudio2022(edition) -y
choco install visualstudio2022-workload-manageddesktop -y
choco install visualstudio2022-workload-nativedesktop -y
choco install visualstudio2022-workload-universal -y
```

Replace `(edition)` with your licensed IDE SKU: community, professional, enterprise

Install required dependencies, after installing Visual Studio IDE or build tools:
```sh
choco install microsoft-openjdk17 ant maven -y
choco install bonjour -y; choco install bonjour -y --force
```

Optional, see Remarks:
```sh
choco install wixtoolset -y
```

_Remarks_: Installing with Chocolatey may or may not fail spectacularly.
Following issues have been observed on a clean installation:
- Bonjour package fails with `file not found` - though the Bonjour64.msi is extracted from BonjourPSSetup.exe.
- wixtoolset depends on .NET 3.5-package, which never completes
  On Windows 11 installation doesn't work
- `visualstudio*-workload-*` may halt with "Operation canceled",
  Abort Chocolatey-command (Ctrl-C), then open up Visual Studio Installer and Resume installation there

Restart your machine after installing these components.

#### System Configuration
Make sure that `MSBuild`, `mvn`, `ant` and `java` are on your `PATH`-environment variable.
* Open `Developer Command Prompt for VS2022`, then run `where msbuild.exe`, add first directory name to path
  * e.g. `C:\Program Files\Microsoft Visual Studio\Community\Msbuild\Current\Bin\amd64`
* Chocolatey may have added mvn and ant to your `PATH`-variable
* The Microsoft OpenJDK 17 installer automatically adds itself to the system `PATH`.

Additionally include the latest Windows Sdk-binary folder in your `PATH`-environment variable:
* `%ProgramFiles(x86)%\Windows Kits\10\bin\10.0.<Latest>.0\x64`

#### NuGet Configuration

To build on Windows, you need to configure NuGet with credentials to access GitHub Package Registry sources. Create a GitHub [personal access token (classic)](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry) with at least `read:packages` permissions.

Then, in the Cyberduck repository root directory, run the following commands in Terminal (PowerShell or Command Prompt):

```sh
dotnet nuget update source gh-ikvmnet -u "YourUsername" -p "YourPAT"
dotnet nuget update source gh-iterate-ch -u "YourUsername" -p "YourPAT"
```

Replace `YourUsername` with your GitHub username and `YourPAT` with your personal access token.

## Building

Run `mvn verify -DskipTests -DskipSign` to build without running any tests and skip codesign. Find build artifacts in

* `osx/target/Cyberduck.app`
* `windows/target/Cyberduck.exe`

Run with `-Pinstaller` to build installer packages with build artifacts

* `osx/target/release/*.(zip|pkg)`
* `windows/target/release/*.(exe|msi)`
* `cli/osx/target/release/*.(pkg|tar.gz)`
* `cli/windows/target/release/*.(exe|msi)`
* `cli/linux/target/release/*.(deb|rpm)`

### macOS

Active the sandboxing profile with `-Psandbox` to apply sandbox entitlements `com.apple.security.app-sandbox`.

### Windows

You will run into warnings from `MSBuild`/`WiX` that are unrelated to how Cyberduck is built. You may safely ignore them.

## Debugging

### macOS

Build with `-Pdebug` to allow attaching the remote debugger on port `5005`.

### Windows

Due to Visual Studio not being able to handle Java projects it is required to follow these steps for debugging:

- Run `mvn verify -Dconfiguration=debug` which ensures that debugging symbols are generated
  This prevents Visual Studio (or `MSBuild invoked from Maven`) from generating optimized assemblies which in turn may
  prevent debugging.
- Open the solution in Visual Studio
- Open a `.java` file and set a breakpoint. Visual Studio breaks either on or near the line selected.
- Debugging capabilities include
  - Step Over
  - Step Into
  - Step Out
  - Continue
  - Local/Auto variables
  - Immediate Window
  
  Go To Symbol is not working due to missing Java support.

## Running Tests

After packaging, run `mvn test -DskipITs` to run unit tests but skip integration tests.

### Maven Artifacts (GPL)

#### Repository Configuration

Maven artifacts are available in a repository hosted on Amazon S3.

- Use the following Maven configuration in your project POM to reference artifacts from Cyberduck

     ```xml
    <repositories>
        <repository>
            maven.cyberduck.io-release
            https://s3-eu-west-1.amazonaws.com/repo.maven.cyberduck.io/releases
            <layout>default</layout>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
    </repositories>
    ```

#### Artifacts

- Protocol implementations

    ```xml
    <dependency>
        <groupId>ch.cyberduck</groupId>
        <artifactId>protocols</artifactId>
        <type>pom</type>
        <version>7.1.0</version>
    </dependency>
    ```

- Cocoa Java Bindings (macOS)

    ```xml
    <dependency>
        <groupId>ch.cyberduck</groupId>
        <artifactId>binding</artifactId>
        <version>7.1.0</version>
    </dependency>
    ```

- Implementations (macOS) using Launch Services, SystemConfiguration, Foundation, Keychain and other API

    ```xml
    <dependency>
        <groupId>ch.cyberduck</groupId>
        <artifactId>libcore</artifactId>
        <version>${project.version}</version>
    </dependency>
    ```

## Sponsors

[](https://www.yourkit.com)

YourKit supports open source projects with its full-featured Java Profiler. YourKit, LLC is the creator of [YourKit Java Profiler](https://www.yourkit.com/java/profiler/)
and [YourKit .NET Profiler](https://www.yourkit.com/.net/profiler/), innovative and intelligent tools for profiling Java and .NET applications.

## 2. Official Technical Reference & Guides (iterate-ch/docs)

# Documentation source for [Cyberduck](https://cyberduck.io), [Cyberduck CLI](https://duck.sh) & [Mountain Duck](https://mountainduck.io)

[](https://github.com/iterate-ch/docs/actions/workflows/CI.yml)

Libre file transfer client for macOS and Windows. Command line interface (CLI) for Linux, macOS and Windows.

## Prerequisites

- Python
- make
- `pip install sphinx`
- `pip install -r requirements.txt`


## Building

Build the documentation by running

```
make html
```

Output can be found in `_build/html`.

## Contributions

Contributions to this documentation are welcome. Please open a pull request.

---

## General Formatting Guidelines

Add an empty line...
- ...after a heading
- ...before and after an admonition or codeblock
- ...after the admonition class for custom admonitions
- ...after a tab opening and before a tab closing as shown in the [Tabs Section](#tabs)
- ...before and after tables
- ...before and after image inserts with custom properties

Indent codeblocks and admonitions within numbered lists, as the numbers aren't rendered correctly otherwise.

### Footnotes

- This is a manually-numbered footnote reference.[^3]
- This is an auto-numbered footnote reference.[^myref]

[^myref]: This is an auto-numbered footnote definition.
[^3]: This is a manually-numbered footnote definition.

A longer footnote definition.[^mylongdef]

[^mylongdef]: This is the _**footnote definition**_.

    That continues for all indented lines

    - even other block elements

    Plus any preceding unindented lines,
that are not separated by a blank line

### Tabs
Group tabs allow selecting a tab for the whole page. As an example: If a page contains three group tabs with macOS and Windows as options, and you select macOS for one section, then all the sections on the page will switch to macOS.

```
::::{tabs}
:::{group-tab} macOS

text

:::
:::{group-tab} Windows

text

:::
::::
```

Regular tabs are limited to the section and doesn't affect any other tabs on the page.

```
::::{tabs}
:::{tab} Text 1

text

:::
:::{tab} Text 2

text

:::
```

### Quotes and Code

````
```
This is a codeblock
```
````

`this is in line code`

```
> this is a single line Quote
```

### Links und Downloads
Add those inline into the text where needed.

```
[Formatting Cheat Sheet](Formatting_Cheat-Sheet)
```

```
{download}`Title<Download_Link>`
```

### Admonitions
Admonitions are boxes with a colored background that highlight information. Available admonition types are: note, warning, tip, caution, attention, danger, error, hint, important, and seealso

```
:::{<type>}
text
:::
```

Admonitions can also be used with custom titles by using the format below.

```
:::{admonition} Custom Title
:class: tip

text
:::
```