README-iOS.md
1# Readme
2
3* [Setup](#setup)
4* [Usage](#usage)
5* [Troubleshooting](#troubleshooting)
6
7## Setup
8
9### [CocoaPods](https://cocoapods.org) (Recommended)
10
111. Add `pod 'STK', '~> 4.6'` to your Podfile.
12
131. Run `pod install`
14
15### Manual
16
171. Clone or [download][download_link] the STK into your project's directory.
18
191. Open the **STK for iOS** folder, and drag and drop **STK.xcodeproj** into your Xcode project.
20
211. Open your project's settings, open the *Build Phases* tab. In the *Link Binary with Libraries* section, add **libSTK.a**.
22![][linking_libSTK_screenshot]
23
241. In the *Dependencies* section, add "rawwaves"
25
261. In your project's settings, open the *Build Settings* tab. In the *Search Paths* section, double click on the field to the right of *Header Search Paths*, and add the path to the STK's **include** directory relative to your Xcode project's directory.
27![][header_search_paths_screenshot]
28
29
30## Usage
31
321. Import the STK classes you require in your Objective-C source files (Swift does not yet support importing C++ code)
33 * E.g. `#import "SineWave.h"`
34
351. Change the extension of any Objective-C files that import STK files to **.mm**.
36 * E.g. **ViewController.m** —> **ViewController.mm**
37
381. If you use a class that makes use of raw wave files (such as `Mandolin`), make sure you call `Stk::setRawwavePath` beforehand in your code.
39
40See the [iOS Demo project](..projects/demo/iOS%20Demo) for a sample usage.
41
42
43## Troubleshooting
44
45### 'FileName.h' file not found
46
47If you get this error when `#import`ing an STK header, you have added the wrong header search path for the STK in your project's settings (see Step 4 in Setup)
48
49The STK's header search path you need to add is the path to the STK's **include** directory relative to your project's directory (as if you were `cd`ing into it). For example, it is `stk/include/` if the stk directory is inside your project's directory, but it is `../stk/include/` if both share the same directory.
50
51If this problem doesn't go away:
52
531. Delete **STK.xcodeproj** from your Xcode project
541. Move the STK directory within your project's directory.
551. Follow step 1 from **Setup**, add `stk/include` to the *Header Search Paths*.
56
57If that doesn't solve it:
58Install CocoaPods and use it to install the STK. It takes one minute and will make your life easier. Visit the [CocoaPods website](https://cocoapods.org) for installation instructions.
59
60### FileRead::open: could not open or find file (../../rawwaves/filename.raw)!
61
62If you use a class that makes use of raw waves (such as `Mandolin`, `Wurley`, or `Rhodey`) you need to make sure that the STK's raw wave files are copied into your bundle and that the STK knows where they are. You'll know you need to if you get this runtime error:
63`FileRead::open: could not open or find file (../../rawwaves/filename.raw)!`
64
65#### If you're using CocoaPods
66
67Add this code before using a class that needs the raw waves:
68```objective-c
69stk::Stk::setRawwavePath([[[NSBundle mainBundle] pathForResource:@"rawwaves" ofType:@"bundle"] UTF8String]);
70```
71
72#### If you're not using CocoaPods
73
741. Open your project's settings, open the *Build Phases* tab.
751. In the *Copy Bundle Resources*, drag and drop **rawwaves.bundle** (it's located in **STK.xcodeproj**'s **Helpers** folder).
761. Then add this code before using a class that needs the raw waves:
77
78```objective-c
79NSBundle *rawwaveBundle = [NSBundle bundleWithURL:[[NSBundle mainBundle] URLForResource:@"rawwaves" withExtension:@"bundle"]];
80stk::Stk::setRawwavePath([[rawwaveBundle resourcePath] UTF8String]);
81```
82
83### Apple Mach-O Linker Error
84
85This means that **STKLib.a** isn't being linked to your binary. Follow step 2 above in [Setup](#setup).
86
87
88[download_link]: https://github.com/thestk/stk/archive/master.zip
89[linking_libSTK_screenshot]: http://i.imgur.com/cLbGrtq.png
90[header_search_paths_screenshot]: http://i.imgur.com/iBTC06h.png
91[rawwaves_scheme_screenshot]: http://i.imgur.com/PKd7epf.png
92
