README.md (8645B)
1 # SFS Client 2 3 [](https://github.com/microsoft/sfs-client/actions/workflows/main-build-windows.yml) [](https://github.com/microsoft/sfs-client/actions/workflows/main-build-ubuntu.yml) 4 5 ## Introduction 6 7 This repository holds the Simple File Solution (SFS) Client, a C++ library that simplifies the interface with the SFS service. 8 Read below to get started on developing and using the library. 9 10 ## Usage 11 12 Follow the [API](API.md) document for tips on how to use the API. 13 14 ## Getting Started 15 16 ### Prerequisites 17 18 #### Setup script 19 20 There are a few dependencies required to work on this project. 21 To set them up, use the Setup script. 22 23 Windows: 24 ```powershell 25 .\scripts\Setup.ps1 26 ``` 27 28 Linux: 29 ```bash 30 source ./scripts/setup.sh 31 ``` 32 33 The script can be run multiple times as it does not replace what has been installed, and updates dependencies. 34 It also sets up useful command-line aliases that can be used while developing. 35 36 ## Consuming the library 37 38 This library is distributed as Source Code and meant for consumption in this format. Below we outline how to easily consume us through the vcpkg tool, but feel free to use other methods to incorporate the source. 39 40 ### vcpkg 41 42 The [vcpkg](https://vcpkg.io/) tool is a Microsoft dependency manager for C/C++. It works "for all platforms, buildsystems, and workflows". 43 In general the dependencies are registered in the central vcpkg registry, where the "portfile" recipes are hosted. These files indicate the way the dependencies should be acquired and built. 44 45 One of the features it provides is also a way to find dependencies listed in the local filesystem. See the [overlay-ports](https://learn.microsoft.com/en-us/vcpkg/concepts/overlay-ports) feature to see that. 46 We are not hosted in the central vcpkg registry, but we provide a template overlay-port for easy consumption of the library. See the [sfs-client-vcpkg-port](./sfs-client-vcpkg-port) folder for the files you need to have in your local repository in order to consume us. A few placeholders have to be filled in on those files. 47 48 ## Formatting 49 50 This project is currently using the clang-format tool to format its source code according to predefined rules. 51 It is also using cmake-format to format the CMakeLists.txt files. 52 Both are installed automatically with the Setup script. 53 54 ### Automatic usage 55 56 The project is configured to automatically run formatting upon committing so nobody introduces 57 unformatted changes to the codebase. This is done through a pre-commit hook. 58 If you must avoid the hook, you can use `git commit -n` to bypass it. 59 60 ### Running on command line 61 62 Use -h to see the binary help: 63 ``` 64 clang-format -h 65 cmake-format -h 66 ``` 67 68 Use -i to edit a file inplace: 69 ``` 70 clang-format -i ./interface.cpp 71 cmake-format -i ./CMakeLists.txt 72 ``` 73 74 Wildcards are accepted in clang-format: 75 ``` 76 clang-format -i ./*.h 77 ``` 78 79 ## Building 80 81 To build, use the `build` command. It simplifies the CMake build commands and re-generates CMake configurations if needed. 82 83 Available build options: 84 85 | Switch (PowerShell) | Switch (Bash) | Description | 86 |----------------------|---------------------------|------------------------------------------------------------------------------------------| 87 | -Clean | --clean | Use this to clean the build folder before building. | 88 | -BuildType | --build-type | Use this to define the build type between "Debug" and "Release". The default is "Debug". | 89 | -EnableTestOverrides | --enable-test-overrides | Use this to enable test overrides. See [TEST](TEST.md) for more. | 90 | -BuildTests <bool> | --build-tests {ON, OFF} | Use this to build tests alongside the library. On by default. | 91 | -BuildSamples <bool> | --build-samples {ON, OFF} | Use this to build samples alongside the library. On by default. | 92 93 See [below](#building-with-cmake-vscode-extension) for building within VSCode. 94 95 ## VSCode 96 97 [Visual Studio Code](https://code.visualstudio.com) is the recommended editor to work with this project. 98 But you're free to use other editors and command-line tools. 99 100 ### Configuring VSCode includes with CMake 101 102 VSCode has a great integration with CMake through the CMake Tools extension (ms-vscode.cmake-tools). 103 It allows you to configure and build the project through the UI. 104 105 Open the command pane on VSCode and search for "C/C++: Edit Configurations (JSON)" to create a c_cpp_properties.json file under a .vscode folder in repo root. 106 The folder is ignored in git by default. 107 Add the following line to the "configurations" element to make VSCode start using the includes defined in the CMakeLists.txt files. 108 109 ```json 110 "configurations": [ 111 { 112 "configurationProvider": "ms-vscode.cmake-tools" 113 } 114 ] 115 ``` 116 117 ### Formatting C++ Sources with VSCode 118 119 Install the extension https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools and Shift+Alt+F inside a file. 120 You can also access "Format" options by right clicking on an open file or over a line selection. 121 122 If you want it, you can also make VSCode format on each Save operation by adding this to your User JSON settings: 123 `"editor.formatOnSave": true` 124 125 ### vcpkg integration 126 127 From [the vcpkg docs](https://github.com/Microsoft/vcpkg/#visual-studio-code-with-cmake-tools): 128 129 Adding the following to your workspace settings.json will make CMake Tools automatically use vcpkg for libraries: 130 131 ```json 132 { 133 "cmake.configureSettings": { 134 "CMAKE_TOOLCHAIN_FILE": "[vcpkg root]/scripts/buildsystems/vcpkg.cmake" 135 } 136 } 137 ``` 138 139 ### Building with CMake VSCode extension 140 141 If you're using the CMake Tools extension on VSCode, you can set the build options through the VSCode settings. Add something like below to either your user or workspace JSON settings to get a default value for an option. You can also later use the command "Edit CMake Cache (UI)" for visual editing. 142 143 ```json 144 "cmake.configureArgs": [ 145 "-DSFS_ENABLE_TEST_OVERRIDES=ON" 146 ] 147 ``` 148 149 See [SFSOptions.cmake](cmake/SFSOptions.cmake) for the CMake options available for the library. 150 151 ## Testing 152 153 Tests are compiled alongside the library by default, and live in the client/tests subdirectory. 154 To run the tests, you can use the `test` command. It will run all tests directly and output the result to the console. 155 156 If you want to customize the test run, you can make use of the `ctest` tool. 157 158 ``` 159 ctest --test-dir ./build/client 160 ``` 161 162 To run specific tests, you can filter the chosen tests through the switch `-R` or `--tests-regex`. 163 For more test selection switches, use `ctest --help`. 164 165 The tests are built using the Catch2 framework. For a more verbose run you can run the executable directly, with -s. 166 167 Windows: 168 ``` 169 .\build\tests\bin\<ReleaseConfiguration>\SFSClientTests.exe -s 170 ``` 171 172 Linux: 173 ``` 174 ./build/tests/bin/SFSClientTests -s 175 ``` 176 177 Follow the [TEST](TEST.md) document for more information regarding testing. 178 179 ## Contributing 180 181 This project welcomes contributions and suggestions. Most contributions require you to agree to a 182 Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us 183 the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. 184 185 When you submit a pull request, a CLA bot will automatically determine whether you need to provide 186 a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions 187 provided by the bot. You will only need to do this once across all repos using our CLA. 188 189 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). 190 For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or 191 contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. 192 193 ## Trademarks 194 195 This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party’s policies.