| Both sides previous revision
Previous revision
Next revision
|
Previous revision
|
getting_started_with_the_projucer [2017/08/29 14:40]
shane [Running the Projucer for the first time] |
getting_started_with_the_projucer [2017/08/31 12:28] (current)
shane [Getting started with the Projucer] |
| The JUCE Projucer is a code and IDE-project generator. You specify what kind of project you want (e.g. GUI application, Audio Plug-In, etc.), and the target IDEs you intend to work with (e.g. Visual Studio, XCode), plus some other details such as a project name, and the Projucer will generate a complete project/solution for each IDE, including a few "starter" code files. You can then open each project/solution in the appropriate IDE, click on "Build" and within a few minutes have a working app or plugin for your target platform. | The JUCE Projucer is a code and IDE-project generator. You specify what kind of project you want (e.g. GUI application, Audio Plug-In, etc.), and the target IDEs you intend to work with (e.g. Visual Studio, XCode), plus some other details such as a project name, and the Projucer will generate a complete project/solution for each IDE, including a few "starter" code files. You can then open each project/solution in the appropriate IDE, click on "Build" and within a few minutes have a working app or plugin for your target platform. |
| |
| Well, that's the theory. In practice, there are lots of little details to understand, which can be overwhelming when you're just getting started. On this page I'll take you step-by-step through building a synthesizer plugin for Windows (VST v2.4) and Macintosh (AU v2). | Well, that's the theory. In practice, there are lots of little details to understand, which can be overwhelming when you're just getting started. On this page I'll take you step-by-step through building a synthesizer plugin called **VanillaJUCE** for Windows (VST v2.4) and Macintosh (AU v2). |
| |
| ===== Creating your first project with the Projucer ===== | ===== Creating your first project with the Projucer ===== |
| * At this point, click the big pink "Create..." button at the bottom left, and the Projucer will immediately generate your first set of IDE projects. | * At this point, click the big pink "Create..." button at the bottom left, and the Projucer will immediately generate your first set of IDE projects. |
| |
| | ===== A quick tour of the Projucer's output ===== |
| | |
| | The Projucer will create a new folder for your new project, containing three subfolders and a ''.jucer'' file: |
| | |
| | {{::projucer-output1.png?nolink|}} |
| | |
| | The ''.jucer'' file is the Projucer project file, containing all the details you specified above. If you double-click this icon you'll re-open the project. |
| | |
| | The ''Source'' folder contains the source code files that are unique to this project. For an Audio Plugin project, there will initially be four files as follows: |
| | * ''PluginProcessor.h'' and ''PluginProcessor.cpp'' define a new subclass of the JUCE //AudioProcessor// class, which represents your plugin itself. |
| | * ''PluginEditor.h'' and ''PluginEditor.cpp'' define a new subclass of //AudioProcessorEditor//, which represents your plugin's GUI. |
| | |
| | I'm not going to go into any detail about the content of these files. You can learn plenty by working through some of the [[https://www.juce.com/tutorials|JUCE tutorials]]. My goal here is to tell you what the tutorials don't mention, which you otherwise have to find out by trial and error. |
| | |
| | The ''JuceLibraryCode'' folder's purpose is explained very nicely in a little ''ReadMe.txt'' file in it: |
| | |
| | > Important Note!! |
| | > ================ |
| | > |
| | >The purpose of this folder is to contain files that are auto-generated by the Projucer, |
| | >and ALL files in this folder will be mercilessly DELETED and completely re-written whenever |
| | >the Projucer saves your project. |
| | > |
| | >Therefore, it's a bad idea to make any manual changes to the files in here, or to |
| | >put any of your own files in here if you don't want to lose them. (Of course you may choose |
| | >to add the folder's contents to your version-control system so that you can re-merge your own |
| | >modifications after the Projucer has saved its changes). |
| | |
| | So, these files are not the entirety of the "Juce Library Code"; the rest is in the JUCE Modules folder we went to such trouble about. These files are simply the few that have to be customized for your specific project. |
| | |
| | The ''Builds'' folder is the most interesting one at this point. Here is what my ''VanillaJuce\Builds'' folder contained, after I selected Xcode (MacOSX), Xcode (iOS), and Visual Studio 2017 as my Target Platforms in the Projucer: |
| | |
| | {{::projucer-output2.png?nolink|}} |
| | |
| | The Projucer created two separate folders for the two XCode targets (Mac and iOS), and one for Visual Studio. These folders can simply be copied as-is over to a Mac, and the XCode project files they contain opened and compiled---//provided you set your Mac global search paths correctly, and installed put the JUCE modules folder and (optionally) VST3 SDK folder in the corresponding locations// (see [[downloading_and_installing_juce#where_to_put_the_juce_folder_and_others_you_may_need|here]] for details. If not, you can always open the Projucer project again, modify the settings, and re-save to re-generate all IDE project files. |
| | |
| | The contents of the ''VisualStudio2017'' folder look like this: |
| | |
| | {{::projucer-output3.png?nolink|}} |
| | |
| | There is a single ''.rc'' file (binary resources), one ''.sln'' (solution) file, and three pairs of ''.vcproj''/''.vcproj.filters'' files for three individual Visual Studio projects: |
| | * one to build the VST plugin (''VanillaJuce_VST'') |
| | * one to build the stand-alone application (''VanillaJuce_StandalonePlugin'') |
| | * one to build a ''.lib'' file from all the code which is common to both plugin and standalone versions |
| | |
| | Of these, the "shared code" file is by far the largest. It contains references to all of the code files in the ''Source'' and ''JuceLibraryCode'' folders, as well as a ton of files in the "JUCE modules" folder (which is why the Projucer needed to know where to find it). The others two projects just contain a couple of wrapper code files. |
| | |
| | ===== Reopening the project in the Projucer and re-generating the output ===== |
| | The Projucer's initial output is based on default settings for Audio Plugin projects. Once you have hit the "Create..." button, the Projucer window will change to something like this: |
| | |
| | {{::projucer-edit1.png?direct&600|}} |
| | |
| | If you decided to close the Projucer, you can simply run it again to get to the same point. The Projucer will normally re-open to whatever project you had open the last time you closed it. If you happened to close the project, then close and re-open the Projucer, You'll see an almost empty window, and you can then get to the same point by going to the File menu to re-open your project's ''.jucer'' file. |
| | |
| | You have several options when you have (re-)opened an already-created Projucer project like this. After making any changes, you can go to the File menu and choose "Save Project" to re-save the ''.jucer'' file **and re-generate all the IDE project files**. |
| | * This is pretty much the whole point of using the Projucer at this stage. |
| | * Bear in mind that **all the IDE project files** (everything in the ''Builds'' and ''JuceLibraryCode'' folders) will be overwritten. I'll tell you how to handle that in a moment. |
| | |
| | As mentioned above, if you got any of your global paths wrong, you can choose "Global Search Paths..." from the File menu and make appropriate changes. |
| | |
| | You can change the //project settings// by clicking on the {{::project-settings-button.png?nolink|}} button, which opens a view like this: |
| | |
| | {{::project-settings.png?direct&600|}} |
| | |
| | The large scrolling list of project settings has lots of items that you can ignore until you're ready to fill them in, e.g. Company Name and Website, but there are a few that you will need to set for a synthesizer plugin: |
| | |
| | {{::project-settings2.png?nolink|}} |
| | |
| | Choose the plugin formats you want to be generate. |
| | |
| | {{::project-settings3.png?nolink|}} |
| | |
| | //Plugin Channel Configurations// are pairs of numbers //{a,b}// where //a// is the number of audio inputs and //b// the number of audio outputs. A synthesizer will normally have no audio inputs (MIDI only) and two output channels (stereo Left/Right). You also have to check the boxes for "Is a Synth" and "Plugin wants midi input" to ensure that your synth plugin(s) will be correctly recognized and set up by whatever DAW or plugin-host program you use. |
| | |
| | The {{::exporter-settings-button.png?nolink|}} button allows you to change the settings for the "exporter" you select using the combo box at the top. Here is the Exporter Settings view for Visual Studio 2017: |
| | |
| | {{::exporter-settings1.png?direct&600|}} |
| | |
| | Note that whenever the exporter settings view is shown, the stacking list on the left changes so the //Exporters// panel is opened and the other (Modules, File Explorer) are closed. You can also click on the "Debug" and "Release" items in the Exporters panel, to select settings specific to Debug and Release builds. |
| | I haven't found the Visual Studio 2017 exporter settings to be all that useful, to be honest. The one option I'd really like to see---the ability to say you want //both// 32- and 64-bit build targets---is not provided. |
| | |
| | The important thing about the exporter settings is **if you make any changes, your project/solution files will get completely rebuilt**, phasering any changes you might have made in your IDE. This leads to the most important thing to understand about the Projucer---two closely-related things, actually: |
| | - You need to give the Projucer enough information to rebuild your project/solution files without losing anything important, and |
| | - This **includes your list of source-code files!** |
| | |
| | This takes us to the "File explorer" and "Modules" panels in the left part of the Projucer window. Let's start with the "File explorer", because it's the simplest. In the File explorer panel, you can use the pink "+" button at the bottom right to add "groups" and individual source-code files, to define the groups and files you want to see in your IDE projects. Most of the time, you will add new source-files and groups in your IDE, as you develop your plugin code, and that's OK, because if you ever need to re-open your ''.jucer'' file and make a change which would cause the IDE projects to get re-generated, you can simply right-click on a group in the File explorer panel and choose "Add existing files..." to add in the appropriate links. **If you forget to do this, your IDE project(s) will no longer contain the files you added previously in the IDE.** Irritating, but no problem; you can always open the Projucer again and fix it. Remember: to trigger re-generation of your IDE files, choose "Save Project" from the Projucer's File menu. |
| | |
| | //For Audio Plugin projects, the Projucer won't re-generate your actual source-code files---at least not the ones in the ''Source'' folder---so you can edit these however you choose. Note this is not always the case for other project types.// |
| | |
| | Here is a screenshot of the Projucer File explorer tab for the finished VanillaJuce project, side-by-side with the Visual Studio solution explorer for the ''VanillaJuce.sln'' solution: |
| | |
| | {{::projucer-file-explorer.png?nolink|}} {{:vs-solution-explorer.png?nolink|}} |
| | |
| | The JUCE library includes a large number of //modules// (each of which consists of many source files) for major kinds of functionality, and the Modules panel allows you to set which of them are included in your IDE projects, and to change their default option-settings should you choose. By default, the Projucer stuffs this with a fairly large set of JUCE modules, including a few (e.g. ''juce_video'') which a typical synthesizer plugin would never need. You can experiment with removing these individually---if you see others turn red, you'll know you've removed a module that these others depend upon---but it isn't important to do so, because your IDE's linker will ensure than only necessary JUCE code gets compiled into your final plugin. |
| | |
| | Normally, you can ignore the Modules panel in the Projucer unless you need to add a module that isn't in the default list---say, the new DSP module in JUCE 5.1. However, if you intend to publish your code as open-source, as I have, you'll need the Modules folder for one more important step: **copying the JUCE modules you use into your source-code tree**. To do this, open the Projucer's Modules panel and click on the little {{::projucer-module-settings-button.png?nolink|}} button at the bottom-left corner (beside the {{::projucer-plus-button.png?nolink|}} button) to open the Module Settings view, which looks like this: |
| | |
| | {{::module-settings.png?direct&600|}} |
| | |
| | Click on the black button labeled "Set copy-mode for all modules..." and choose "Set all modules to copy locally" from the resulting pop-up menu; all entries in the "Make Local Copy" column will change to "Yes". When you close your Projucer project, not only will the various IDE project/solution files get rebuilt as usual, a new subfolder called //modules// will be added to your project's //JuceLibraryCode// folder, containing all of the JUCE module source files your project requires. |
| | |
| | If you're using GitHub, your next commit will take some time, as //git// absorbs all of the many newly-added JUCE source files. The result will be worth it, though, because it will make your GitHub repository entirely self-contained. When Roli eventually releases the next version of the JUCE library, which quite probably includes code-breaking changes, your published code will continue to use the older versions which have been checked-in along with your own code, and hence won't break. |
| | |
| | ===== Other things you can do with the Projucer ===== |
| | The Projucer is an evolving software product. It has many other features and capabilities I haven't touched on here, and I encourage you to explore them at your own pace. It includes a "live build" capability, whereby it can work essentially as an IDE, complete with a syntax-coloring source-file editor, but I confess I haven't found this very useful. I'm more comfortable working in Visual Studio or Xcode. The live-build capability seems to be something of an experimental new feature, related to the Projucer's built-in GUI Editor. |
| | |
| | The Projucer's GUI editing features also appear to be somewhat experimental, and so far, seem mostly useful for creating stand-alone GUI applications. The basic idea is that, in the File explorer tab, you can right-click and choose "Add New GUI Component..." and specify a new class name, and the Projucer will create a ''.h''/''.cpp'' file pair for a new class derived from JUCE's //Component// class. When you click on the ''.cpp'' file in the File explorer, the right window will not only show the C++ code, it will also allow you (with tabs along the top of the edit view) to see and edit a graphical view of the GUI layout. This can even work together with the Projucer's live-build capability, to allow you to open and interact with a live version of whatever kind of GUI view you're defining. |
| | |
| | This is all very exciting and high-tech, but to be honest, I don't like working this way. It requires that your source-code files be peppered with special comments, which guide the Projucer's GUI Editor in parsing it, and your own additions must be carefully confined to specific regions designated by these comment-tags. I find the Projucer's GUI editing features more useful simply as a tool to generate known-good JUCE GUI code. |
| | |
| | The way I use the Projucer for GUIs is to create a new GUI Application project, use the GUI editing features to lay out a basic GUI incorporating all the elements I'm interested in (buttons, sliders, etc.), then generate the project and look inside the generated ''.h''/''.cpp'' files for code I can cut-and-paste into the GUI parts of, say, a synthesizer plugin project (working in my trusty IDE). In this respect, the Projucer is simply a dynamite adjunct to the JUCE API documentation, which is pretty complete but doesn't include any working examples. What's great about the Projucer is that it always generates working code. This is how I developed the tabbed GUI used in the VanillaJuce synthesizer plugin. |
| |
| |
