| Both sides previous revision
Previous revision
Next revision
|
Previous revision
|
getting_started_with_the_projucer [2017/08/29 19:44]
shane [Reopening the project in the Projucer and re-generating the output] |
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 ===== |
| 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. | 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. |
| |
| Here is a screenshot of the Projucer's File explorer tab for the finished VanillaJuce project, side-by-side with the Visual Studio solution explorer for the ''VanillaJuce.sln'' solution: | //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|}} | {{::projucer-file-explorer.png?nolink|}} {{:vs-solution-explorer.png?nolink|}} |
| |
| //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.// | |
| |
| 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. | 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. |
| |
| |
