Differences

This shows you the differences between two versions of the page.

--- guru-files [2021/09/03 20:17] – shane
+++ guru-files [2023/05/08 18:59] (current) – external edit 127.0.0.1
@@ Line 25: / Line 25: @@
 When this //.guru// file is dropped into the Unify GUI, Unify will unzip its contents into the main data folder. Hence, everything inside the //Libraries// folder in the //.guru// file will go into the //Libraries// folder in the main Unify data folder, and everything inside the //Presets// folder will go into //Presets//.
-**Any folders present in the //.guru// file, which don't yet exist in the corresponding locations under the main Unify data folder, will get created automatically.** This is why it is VERY important to get the folders inside your //.guru// files just right, or files and folders will go into the wrong places, and anyone to whom you send your //.guru// file will end up with a mess to clean up.
+What happens is exactly the same as if you put the //.guru// file itself into the main Unify data folder, and unzipped its contents using the "extract here" option. (Different systems may use different wording to describe this, but the effect is the same, as described in the next section.)
+===== How Unify unzips the .guru file =====
+Any **folders** present in the //.guru// file, which don't yet exist in the corresponding locations under the main Unify data folder, will **get created automatically.** This is why it is VERY important to get the folders inside your //.guru// files just right, or files and folders will go into the wrong places, and anyone to whom you send your //.guru// file will end up with a mess to clean up.
+Individual **Files** present in the //.guru// file will be **created** if they don't already exist, but if a file by the same name does exist in that location, it will be **overwritten** with the new file. This is another reason to be very careful when setting up //.guru// files.
+If the //.guru// file contains any patch files (i.e., files which go into the //Patches// sub-folder of any Library folder), Unify will take note of the library name (i.e., the name of the parent folder of the //Patches// folder containing the patch file) and trigger the [[playing-patches#about_the_patch_database|patch database]] to rebuild only for that library (or libraries, if more than one are present).
+===== Limitations of .guru files =====
+When Unify unzips the contents of a //.guru// file, it can only //add// or //overwrite// files (and folders as required). //It cannot delete files.// Some capability to do this may be added to Unify in the future, but there is none at the moment.
+===== Creating a .guru file (the safe way) =====
+Suppose you have created a new library called //My Awesome Library// in Unify, and you'd like to make a //.guru// file to help others install it quickly. Here are the steps:
+  - Start by creating an empty "working folder" somewhere, preferably //not// under the main Unify data folder.
+  - Open your working folder, and also the main Unify data folder, in //Windows Explorer// or Mac //Finder//.
+    * To quickly open the main Unify data folder, click the "gear" icon to go to the [[settings|Settings view]], and click the "Open..." button there.
+  - In the window representing your working folder:
+    * Create an empty //Libraries// folder, and open it
+  - In the main Unify data folder window:
+    * Navigate into the //Libraries// folder
+    * Locate the folder for your library (in this case //My Awesome Library//)
+  - **Copy** the entire //My Awesome Library// folder to the empty //Libraries// sub-folder of your working folder
+  - In your working-folder window, navigate back up to where you started (where you see the //Libraries// folder you made at step 3).
+  - Select the //Libraries// folder, and zip it, using whatever mechanism your computer provides to make //.zip// files, e.g.:
+    * On a Mac, right-click the //Libraries// folder and choose "compress"
+    * On a Windows PC with [[https://www.7-zip.org/|7-zip]] installed, right-click the //Libraries// folder and choose "add to ... .zip" (the name will be the name of your working folder).
+  - Rename the resulting //.zip// file to whatever you want, and //change the extension from .zip to .guru//.
+    * Your operating system will pop up some kind of message asking you to confirm that you really want to change the extension to //.guru//.
+    * Click "OK" or respond in whatever is the appropriate way, to confirm that you want to change the extension.
+At this point, assuming you followed the above steps precisely, you will have a valid //.guru// file, which others can now use to install //My Awesome Library// quickly.
+If you want to upload your //.guru// file to some kind of file-sharing service, attach to an email, etc., it's usually best to //re-zip// the //.guru// file, and share/attach the resulting //.zip// file. Advise recipients that they must unzip it, then drag/drop the resulting //.guru// file into the Unify GUI, or use the //Select .guru file...// button in the [[settings|Settings view]] and select it that way.
+===== Creating a .guru file (the risky way) =====
+If you know what you're doing, you can use these steps instead:
+  - Open the main Unify data folder, and navigate into //Libraries//
+  - Create a new empty //Libraries// folder (inside the //Libraries// folder)
+  - Drag (i.e., move) your own library folder into this new //Libraries// folder
+  - Compress the new //Libraries// folder to a //.zip// file (e.g. //Libraries.zip//), then rename using the //.guru// extension, and confirm as described above.
+  - Make sure to move your library folder back out into the main //Libraries// folder, then delete the dummy //Libraries// sub-folder you created.
+===== Creating a .guru file (more generic) =====
+The above instructions described how to make a //.guru// file for a single patch library, but //.guru// files can contain multiple libraries, or no libraries (i.e., no top-level //Libraries// folder at all), and anything else that belongs under the main Unify data folder, e.g., you may have a top-level //Presets// folder as in the example, or //MIDI Bank Files//, //MIDI Controller Files//, etc. In such cases, it's strongly advisable to use a working folder.
+Whatever you do, just make sure that the folder structure of your //.guru// file exactly corresponds to where all of your own files need to go.
+===== Testing your .guru files =====
+It's a very good idea to test dragging your //.guru// file into Unify, to make sure everything goes into the right places. The best way to do this is to create a second "main Unify data folder" somewhere on your disk, and select in Unify using the "Change..." button in the [[settings|Settings view]]. That way, there will be no risk of messing up your actual Unify data folder contents, and you can switch back after you're finished testing.
+To create a second Unify data folder:
+  - Create an empty folder in a suitable location on your disk, then create empty //Libraries// and //Presets// folders inside it.
+    * If you do not create these sub-folders, Unify will not allow you to select the folder as your main Unify data folder.
+  - In Unify, go to the Settings view, click the "Change..." button, and choose your new folder.
+  - IMPORTANT: **Quit Unify** immediately.
+    * This step ensures that your patch database will not be damaged.
+  - Optionally, copy over any other content you may want (patch libraries, presets, etc.) from your real Unify data folder to your testing folder.
+    * Be very careful that to COPY (not MOVE) files/folders to your test data folder
+  - Re-start Unify
+    * Unify will automatically create an empty database file //presets.db// in your test //Libraries// folder.
+    * If you copied over any libraries, click the lightning-bolt icon at the top of the patch browser, to update this newly-created database to include entries for whatever patches you copied.
+  - Optional, but recommended: Quit Unify again, and zip up your entire test folder.
+    * This will allow you to delete and re-create it quickly, for future tests.
+  - Drag/drop your //.guru// file, and verify that Unify responds as you would wish.
+  - Examine the contents of your test data folder carefully, and verify that all files/folders went into the right places.
+If you notice any problems at steps 7/8, you will need to re-build your //.guru// file accordingly. Before trying it again, delete your entire test data folder, and re-create it as it was at step 6, by unzipping the zip file you created at step 6. Then you can simply re-start Unify and repeat steps 7/8.
+When you are finished testing:
+  - Go to Settings, click the "Change..." button, and re-select your original Unify data folder.
+  - **Quit Unify** immediately, then re-start
+    * Everything should now be back exactly as it was, including your patch database.