opus plus installation guide v1.0

Opus+ Installation Guide v1.0

Adrian Marriott

Date: 9th May 2011

web: http://opusplus.org

http://opusplus.org/

Opus_Plus_Installation_Guide_v1.0 of 26

Copyright (C) 2011 Adrian Marriott

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

GNU Free Documentation LicenseVersion 1.3, 3 November 2008

Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. <http://fsf.org/>

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

The "publisher" means any person or entity that distributes copies of the Document to the public.

A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition.


http://fsf.org/

The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

3. COPYING IN QUANTITY

If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

• A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.

• B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.

• C. State on the Title page the name of the publisher of the Modified Version, as the publisher.

• D. Preserve all the copyright notices of the Document.

• E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.

• F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.

• G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.

• H. Include an unaltered copy of this License.

• I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.


• J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.

• K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.

• L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.

• M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.

• N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.

• O. Preserve any Warranty Disclaimers.

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

5. COMBINING DOCUMENTS

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements".

6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.


8. TRANSLATION

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.

However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.

Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.

10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Document.

11. RELICENSING

"Massive Multiauthor Collaboration Site" (or "MMC Site") means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A "Massive Multiauthor Collaboration" (or "MMC") contained in the site means any set of copyrightable works thus published on the MMC site.

"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.

"Incorporate" means to publish or republish a Document, in whole or in part, as part of another Document.

An MMC is "eligible for relicensing" if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.

The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.


http://www.gnu.org/copyleft/

Table of Contents Opus+ Installation Guide ................................................................................. P. 91 Introduction .................................................................................................... P. 92 Software Dependencies ................................................................................. P. 92.1 Java Version ............................................................................................... P. 92.2 Web Browser .............................................................................................. P. 92.3 LilyPond .................................................................................................... P. 103 Opus+ Distribution Kit .................................................................................. P. 104 Opus+ Installation ........................................................................................ P. 114.1 Opus+ Library Installation ......................................................................... P. 114.2 Testing the Opus+ Library Installation ...................................................... P. 124.3 Opus+ GUI Installation ............................................................................. P. 174.4 Testing the Opus+ GUI Installation ........................................................... P. 185 Installation Trouble-Shooting ....................................................................... P. 225.1 LilyPond Program Not Found .................................................................. P. 225.2 Edit Opus+ Settings Manually .................................................................. P. 235.3 Finding the LilyPond Executable .............................................................. P. 245.4 Log4J Class Not Found ............................................................................ P. 255.5 Double-Clicking Opus+ JAR and LilyPond Fails ..................................... P. 255.6 Web-Browser Shows Blank Page ............................................................. P. 265.7 Further Help and Information ................................................................... P. 26


Opus+ Installation Guide

1 IntroductionThis document explains how to install Opus+ and produce a composition to test the installation. It is recommended that users read the Opus+ Conceptual Overview to get the most out of Opus+ before they start using it regularly.

Installing Opus+ is simply a matter of unzipping files into a directory of your choice; typically this would be the directory from which you intend to use Opus+. Opus+ does NOT change anything on your computer without your knowledge. For example it does not read the Windows registry, set environment variables or in any way communicate across the web to other websites. It does not look for updates, or push you into upgrades. You can remove it from you system if you decide you don't want it by simply deleting everything that you unzipped.

2 Software DependenciesOpus+ is written entirely in the language Java, one advantage of which is portability – 'write once run anywhere' – and this helps to reduce dependencies on particular operating system features. Every effort has been made to minimize Opus+ software dependencies, which are listed below:

• Java version

• Web Browser

• LilyPond

2.1 Java VersionOpus+ requires the Java JRE v1.6 to be installed on the computer running Opus+. Opus+ has been used on systems using 1.5 but this is not a tested configuration; the software was developed using JRE v1.6 [1] Java programmers wishing to write code that uses the Opus+ library will need the Java SDK v1.6 or later In either case to use Opus+ it is preferable to be able to run java from the command line.

You can check java runs from the command line, and what version of the java JRE is loaded onto your system, by opening a 'Terminal Window' [2] and typing the following command at the prompt :

java -version

You should see output similar to the following:

Last login: Tue May 24 12:33:03 on consoleAdrian-Marriotts-MacBook-Pro:~ adrian$ java -versionjava version "1.6.0_15"Java(TM) SE Runtime Environment (build 1.6.0_15-b03-219)Java HotSpot(TM) 64-Bit Server VM (build 14.1-b02-90, mixed mode)

2.2 Web BrowserOpus+ displays its output using the default web browser on your computer. Almost any modern web browser will do including: Mozilla FireFox, Safari, Google Chrome or Microsoft Internet Explorer.

Your default browser will require two plugins to use Opus+ properly:

1 The precise version used during development is: Java(TM) SE Runtime Environment 1.6.0_15-b03-219

2 Also called a 'Console Window' or a 'Command Window' and even a 'command line' or a 'command prompt', or though strictly the former is the line of text displayed in the terminal window and the later is the actual prompt that is displayed on the far left of this command line..


1. Acrobat PDF Reader plugin to view the scores generated.2. A plugin for listening to the MIDI files created by Opus+

2.3 LilyPondThe output of Opus+ is an ASCII file in 'LilyPond' format. LilyPond is a music engraving program, devoted to producing the highest-quality sheet music possible. It brings the aesthetics of traditionally engraved music to computer printouts. LilyPond is free software and is available here:

http://lilypond.org/

Opus+ v1.0 is developed against LilyPond v2.14.1 so Opus+ should work with this, or any later version. Opus+ (optionally) invokes LilyPond as an external process, and simply needs LilyPond to be installed in a default configuration. Specifically it should be possible to run LilyPond from the command line.

To check if this is possible, and to see which version of LilyPond your system has installed open a 'Terminal Window' and type the following command at the prompt:

lilypond -version

You should see output similar to the following:

GNU LilyPond 2.14.1

Copyright (c) 1996--2011 by Han-Wen Nienhuys <[email protected]> Jan Nieuwenhuizen <[email protected]> and others.

This program is free software. It is covered by the GNU General Public. License and you are welcome to change it and/or distribute copies of it under certain conditions. Invoke as `lilypond --warranty' for more information.

3 Opus+ Distribution KitOpus+ v1.0 has two different independent components:

• Opus+ library• Opus+ GUI

and they are downloaded in two different files:

• opusplus_v1.0.zip

• opusgui_v1.0.zip

They are independent in that each is a stand-alone component. Specifically you do not need to install the Opus+ library to use the Opus+ GUI.


mailto:[email protected]


http://lilypond.org/

4 Opus+ InstallationBoth these components are installed by basically unzipping them into directories of your choice.

4.1 Opus+ Library InstallationTo install the library simply download the file opusplus_v1.0.zip and unzip into a directory of your choice. When the file is unzipped you will see the following directories:

• bin

• build

• build.xml

• docs

• examples

• javadoc

• lib

• license

• resources

• src

These directories contain what most developers would expect. The bin directory contains the opusplus.jar file which is the library you must include in your build environment if you wish to program using the Opus+ library.

The build directory contains the class files created during the compilation and packaging of the opusplus.jar file.

The build.xml file is an ant file which rebuilds the opusplus.jar file [3]. The jar is built with debug information left in so you can step into the Opus+ code when using the debugger.

The docs directory contains all the Opus+ documentation as PDF files.

The examples directory contains several independent java code examples that range from the Opus+ 'hello world' to a more realistic program of around 2K lines.

The javadoc directory contains the standard Java documentation for the public Opus+ API v1.0.

The lib directory contains 3rd party java libraries. The only library in here is the excellent log4j-1.2.14.jar

The license directory contains a copy of the GPL3 license which covers Opus+ usage.

The resources directory is empty, and provided for no particular reason.

The src directory contains all the java source code for the Opus+ library [4].

3 The version of Ant used during Opus+ development is: Apache Ant version 1.7.0

4 There are approximately 160K lines of code in the Opus+ library.


Hereafter in this document the location of the Opus+ library will be referred to as the Opus+ library root and will appear in commands as <OPUSLIB_ROOT_DIR> indicating that you must substitute the actual directory path for this token.

4.2 Testing the Opus+ Library InstallationThe Opus+ library jar is runnable. To test the installation:

• Open a terminal• Change into the <OPUSLIB_ROOT_DIR>/bin directory • Run the jar from the command line with the following command:

java -jar opusplus.jar -p

This tests that all the required components are available and work together by creating a random composition. It tests that the java command is working, that LilyPond is accessible and can be invoked from Opus+. You should see many lines of output streaming down the screen starting with something similar to the following:

Adrian-Marriotts-MacBook-Pro:bin adrian$ java -jar opusplus.jar -p

0 [main] INFO root - Opus+ messages: no Log4J properties file supplied. Using basic configuration

1 [main] INFO root - Opus+ messages: setting informational messages only, level=1 (default)

18 [main] INFO opusplus.lib.OpusLib - =======================================

19 [main] INFO opusplus.lib.OpusLib - Purpose: Opus+ Machine Composition, Version: 1.0, Release Date: 9th May 2011, Author: Adrian Marriott. Copyright (c) 2005, 2006, 2007, 2008, 2009, 2010, 2011 Adrian Marriott. All Rights Reserved.

24 [main] INFO opusplus.lib.OpusLib - Started: 15-06-11 05:13:13

24 [main] INFO opusplus.lib.OpusLib - Arguments: [-p]

24 [main] INFO opusplus.lib.OpusLib - Current working dir: /Users/adrian/ajmroot/OPUS-KITS/version-1,0/bin

25 [main] INFO opusplus.lib.OpusLib - PATH=/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/usr/X11/bin:/Users/adrian/ajmroot/bin:/usr/local/mysql/bin


26 [main] INFO opusplus.lib.OpusLib - Java VM Vendor: Apple Inc.

26 [main] INFO opusplus.lib.OpusLib - Java VM Details: Java HotSpot(TM) 64-Bit Server VM 14.1-b02-90 mixed mode

26 [main] INFO opusplus.lib.OpusLib - Java Runtime: Java(TM) SE Runtime Environment 1.6.0_15-b03-219

26 [main] INFO opusplus.lib.OpusLib - Java Home: /System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home

26 [main] INFO opusplus.lib.OpusLib - Java Library Path: .:/Library/Java/Extensions:/System/Library/Java/Extensions:/usr/lib/java

26 [main] INFO opusplus.lib.OpusLib - CLASSPATH: opusplus.jar

26 [main] INFO opusplus.lib.OpusLib - =======================================...

Notice that Opus+ prints out information about its execution environment to assist with troubleshooting. Particularly notice the highlighted text in bold – the $PATH and the $CLASSPATH environment variables which are both sources of common problems when running java applications.


...34 [main] INFO opusplus.programs.Main - Constructing PhraseMaker using no constraints file

35 [main] INFO opusplus.lib.OpusLib -

35 [main] INFO opusplus.lib.OpusLib - Opus+ reinitialization request: FULL

36 [main] INFO opusplus.core.streams.numberStreams.IntegerStreamBase - Re-seeding all integer streams ...

114 [main] INFO opusplus.lib.OpusLib - Attempting to find Opus+ settings file: /Users/adrian/ajmroot/OPUS-KITS/version-1,0/bin/OpusPlusSettings.xml

115 [main] WARN opusplus.lib.OpusLib - Could not find Opus+ settings file: OpusPlusSettings.xml

115 [main] INFO opusplus.lib.OpusLib - Lilypond Cmd String parameter set to: lilypond

115 [main] INFO opusplus.core.utilities.Misc - Searching for executables on $PATH called: lilypond or lilypond.exe

115 [main] INFO opusplus.core.utilities.Misc - Parsing system path:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/usr/X11/bin:/Users/adrian/ajmroot/bin:/usr/local/mysql/bin

115 [main] INFO opusplus.core.utilities.Misc - Found directory: /usr/bin

115 [main] INFO opusplus.core.utilities.Misc - Found directory: /bin

115 [main] INFO opusplus.core.utilities.Misc - Found directory: /usr/sbin

115 [main] INFO opusplus.core.utilities.Misc - Found directory: /sbin

115 [main] INFO opusplus.core.utilities.Misc - Found directory: /usr/local/bin

116 [main] INFO opusplus.core.utilities.Misc - Found directory: /usr/X11/bin

116 [main] INFO opusplus.core.utilities.Misc - Found directory: /Users/adrian/ajmroot/bin

116 [main] INFO opusplus.core.utilities.Misc - Found directory: /usr/local/mysql/bin

116 [main] INFO opusplus.core.utilities.Misc - Getting system path: returning array of directories, size=8

116 [main] INFO opusplus.core.utilities.Misc - Finding executables called: lilypond or lilypond.exe

116 [main] INFO opusplus.core.utilities.Misc - Looking in directory: /usr/bin

129 [main] INFO opusplus.core.utilities.Misc - Looking in directory: /bin

129 [main] INFO opusplus.core.utilities.Misc - Looking in directory: /usr/sbin

132 [main] INFO opusplus.core.utilities.Misc - Looking in directory: /sbin

133 [main] INFO opusplus.core.utilities.Misc - Looking in directory: /usr/local/bin

133 [main] INFO opusplus.core.utilities.Misc - Looking in directory: /usr/X11/bin

135 [main] INFO opusplus.core.utilities.Misc - Looking in directory: /Users/adrian/ajmroot/bin

135 [main] INFO opusplus.core.utilities.Misc - Found executable: /Users/adrian/ajmroot/bin/lilypond

135 [main] INFO opusplus.core.utilities.Misc - Finding executable 'lilypond' on path returning: /Users/adrian/ajmroot/bin/lilypond

135 [main] INFO opusplus.lib.OpusLib - Lilypond executable found on $PATH: /Users/adrian/ajmroot/bin/lilypond


135 [main] INFO opusplus.lib.OpusLib - Saving current parameters to Opus+ settings file.

142 [main] INFO opusplus.lib.OpusLib - Opus+ built for Lilypond version: 2.14.1

142 [main] INFO opusplus.lib.OpusLib - Lilypond command string: lilypond...

Running Opus+ from the command line the first time is important because it attempts to find a settings file called OpusSettings.xml – failing to find it Opus+ creates it and fills it with 'sensible' default values. One of these is the absolute path to the LilyPond executable. Opus+ attempts to find this executable by searching all the directories specified in the $PATH environment variable to check that LilyPond is accessible. Parts of this processing are shown above in bold [5]. Opus+ then goes on to print out the values in the settings file as shown below:

. . .142 [main] INFO opusplus.lib.OpusLib - Opus+ settings XML file: /Users/adrian/ajmroot/OPUS-KITS/version-1,0/bin/OpusPlusSettings.xml

142 [main] INFO opusplus.lib.OpusLib - Run Lilypond automatically: true

142 [main] INFO opusplus.lib.OpusLib - Lilypond file versioning strategy: MONOTONIC_FOLLOW_LARGEST

142 [main] INFO opusplus.lib.OpusLib - Lilypond file version number width: 4

143 [main] INFO opusplus.lib.OpusLib - Create single score: true

143 [main] INFO opusplus.lib.OpusLib - Create separate instrument scores: false

143 [main] INFO opusplus.lib.OpusLib - Bars per single score file: 100

143 [main] INFO opusplus.lib.OpusLib - Bars per separate instrument score file: 100

143 [main] INFO opusplus.lib.OpusLib - Minimum bars per score file: 16

143 [main] INFO opusplus.lib.OpusLib - Prefer break score files at section boundaries: true

144 [main] INFO opusplus.lib.OpusLib - Compress parameter frame XML: DEFAULT_VALUE_DIFF

144 [main] INFO opusplus.lib.OpusLib - Use system parameter XML reference: false

144 [main] INFO opusplus.lib.OpusLib - Save parameter frames to file: true

144 [main] INFO opusplus.lib.OpusLib - Voicepart to PF reference strategy: EACH_VP_HAS_OWN_COPY

144 [main] INFO opusplus.lib.OpusLib - Infinite loop timeout: 120 secs

144 [main] INFO opusplus.lib.OpusLib - Max # retries: 8

145 [main] INFO opusplus.lib.OpusLib - Pause between retries: 10 ms

145 [main] INFO opusplus.lib.OpusLib - Generate example java code: true

145 [main] INFO opusplus.lib.OpusLib - Java file versioning strategy: OVERWRITE


After which Opus+ starts to compose some simple musical phrases …

145 [main] INFO opusplus.lib.OpusExecutor - Running Opus+ executable

146 [main] INFO opusplus.lib.OpusExecutor - Initializing Opus+ executor ...

146 [main] INFO opusplus.lib.OpusExecutor - Execution attempt#: 1 of 8

5 If LilyPond is not found on the path there are many warning messages printed. There are several ways to fix this. Please refer to the section on trouble-shooting in this document.


147 [main] INFO opusplus.lib.OpusExecutor - Main thread 1 JOINING Opus+ run-thread 9: timeout delay = 120 secs

147 [Thread-0] INFO opusplus.lib.OpusExecutor - Opus+ run-thread 9 starting

147 [Thread-0] INFO opusplus.lib.PhraseCreator - PhaseMaker parameters file: not specified.

196 [Thread-0] INFO opusplus.lib.PhraseCreator - Created ChaoticIntegerStream integer stream: id=1

202 [Thread-0] INFO opusplus.core.utilities.Utils - Novel key/time/tempo constraints specified: key=A_MINOR_SCALE (DORIAN_MODE), time=4/4, tempo=115 bpm

205 [Thread-0] INFO opusplus.lib.PhraseCreator - Using default parameter frame for both voices

253 [Thread-0] INFO opusplus.lib.PhraseCreator - Making phrases using: Guitar (ACOUSTIC_GUITAR_NYLON)

254 [Thread-0] INFO opusplus.lib.PhraseCreator - Created NumerologyIntegerStream integer stream: id=3

254 [Thread-0] INFO opusplus.lib.PhraseCreator - Create a set of between 3 & 12 MUSICAL Fragments : settled on 7

261 [Thread-0] INFO opusplus.lib.PhraseCreator - Creating relatively unrelated fragments for Guitar (a single voice)

...

We have cut the number of messages for the sake of brevity, but at the end if the test is successful you should see LilyPond being invoked; something similar to the following:

...

588 [Thread-0] INFO opusplus.lib.PhraseCreator - Invoking Lilypond.

589 [Thread-0] INFO opusplus.lib.misc.ProcessRunner - Opus+ Process Runner: detected operating system is 'Mac OS X'

592 [Thread-0] INFO opusplus.lib.misc.ProcessRunner - Opus+ Process Runner: using general 'Apple Mac' command invocation

592 [Thread-0] INFO opusplus.lib.misc.ProcessRunner - Opus+ Process Runner Executing: lilypond /Users/adrian/ajmroot/OPUS-KITS/version-1,0/bin/opusWorkArea/All_Guitar_Phrases_v0001.ly

1009 [Thread-1] INFO opusplus.lib.misc.StreamGobbler - Lilypond> Processing `/Users/adrian/ajmroot/OPUS-KITS/version-1,0/bin/opusWorkArea/All_Guitar_Phrases_v0001.ly'

1157 [Thread-1] INFO opusplus.lib.misc.StreamGobbler - Lilypond> Parsing...

1176 [Thread-1] INFO opusplus.lib.misc.StreamGobbler - Lilypond> Interpreting music... [8]

1534 [Thread-1] INFO opusplus.lib.misc.StreamGobbler - Lilypond> Preprocessing graphical objects...

1537 [Thread-1] INFO opusplus.lib.misc.StreamGobbler - Lilypond> Interpreting music...

1546 [Thread-1] INFO opusplus.lib.misc.StreamGobbler - Lilypond> MIDI output to `All_Guitar_Phrases_v0001.midi'...

1549 [Thread-1] INFO opusplus.lib.misc.StreamGobbler - Lilypond> Finding the ideal number of pages...

1550 [Thread-1] INFO opusplus.lib.misc.StreamGobbler - Lilypond> Fitting music on 1 page...

1581 [Thread-1] INFO opusplus.lib.misc.StreamGobbler - Lilypond> Drawing systems...

1597 [Thread-1] INFO opusplus.lib.misc.StreamGobbler - Lilypond> Layout output to `All_Guitar_Phrases_v0001.ps'...


2167 [Thread-1] INFO opusplus.lib.misc.StreamGobbler - Lilypond> Converting to `./All_Guitar_Phrases_v0001.pdf'...

2167 [Thread-1] INFO opusplus.lib.misc.StreamGobbler - Lilypond> success: Compilation successfully completed

2177 [Thread-0] INFO opusplus.lib.misc.LilypondRunner - Any generated Lilypond files will be found in: /Users/adrian/ajmroot/OPUS-KITS/version-1,0/bin/opusWorkArea

2178 [Thread-0] INFO opusplus.lib.file.HTMLReviewFileWriter - Generating HTML review file ...

2179 [Thread-0] INFO opusplus.lib.file.HTMLReviewFileWriter - HTML review file path: /Users/adrian/ajmroot/OPUS-KITS/version-1,0/bin/opusWorkArea/All_Guitar_Phrases_v0001.html

2180 [Thread-0] INFO opusplus.lib.file.HTMLReviewFileWriter - Generating HTML review file: complete

2180 [Thread-0] INFO opusplus.lib.OpusExecutor - Opus executable completed.

2181 [main] INFO opusplus.lib.OpusExecutor - Sleeping for 10 ms ...

2191 [main] INFO opusplus.lib.OpusExecutor - -------------------------------------------------------------

2191 [main] INFO opusplus.lib.OpusExecutor - Running Opus+ executable complete: ok=true

2191 [main] INFO opusplus.programs.Main -

2191 [main] INFO opusplus.programs.Main - Et Voila!

Adrian-Marriotts-MacBook-Pro:bin adrian$

Upon completion there will be new items in the <OPUSLIB_ROOT_DIR>/bin directory (your current directory). The location of these items is shown in the messages above highlighted in bold. To view the PDF score and listen to the generated MIDI simply open the HTML review file that has been created.

A list of the items created in bin are:

• OpusPlusSettings.xml• opusWorkArea

The list of items created in the new opusWorkArea are:

• A LilyPond file – extension .ly• A MIDI file – extension .midi• A PDF file - extension .pdf• A PostScript file – extension .ps• A HTML file – extension .html

The LilyPond file contains the raw LilyPond markup written by Opus+.

The MIDI file contains a basic rendition of the composition and can be listened to directly, exported and then played by an external synthesizer, or imported into a Digital Audio Workstation (DAW) such as Apple Logic Pro.

The PDF file contains a score which provides a sketch of the work in standard musical notation.

The PostScript file can be ignored unless you have no way of viewing or printing PDF files. These can safely be deleted.

The HTML file is provided to ease the process of review. It provides a very simple way of listening to the MIDI file while allowing the user to scroll through the score by hand following the music by eye.


4.3 Opus+ GUI InstallationTo install the Opus+ GUI simply download the file opusgui_v1.0.zip and unzip into a directory of your choice [6]. When the file is unzipped you will see the following directories:

• bin

• build

• build.xml

• docs

• lib

• license

• resources

• src

These directories contain the standard components. The bin directory contains the opusgui.jar file which is the program you run to use the Opus+ GUI..

The build directory contains the class files created during the compilation and packaging of the opusgui.jar file.

The build.xml file is an ant file which rebuilds the opusgui.jar file [7].

The docs directory contains all the Opus+ documentation as PDF files.

The lib directory contains 3rd party java libraries. The only library in here is the excellent log4j-1.2.14.jar

The license directory contains a copy of the GPL3 license which covers Opus+ usage.

The resources directory contains two Java .properties files used for the purposes of internationalization [8]. There is also an icons subdirectory which holds all the icons used in the Opus+ GUI.

The src directory contains all the java source code for the Opus+ GUI [9].

Hereafter in this document the location of the Opus+ GUI will be referred to as the Opus+ GUI root and will appear in commands as <OPUSGUI_ROOT_DIR> indicating that you must substitute the actual directory path for this token.

6 The Opus+ GUI is fully self-contained. It is NOT necessary to install the Opus+ Library separately in addition to the Opus+ GUI.

7 The version of Ant used during Opus+ development is: Apache Ant version 1.7.0 8 Only English is currently available.

9 There are around 174K lines in the Opus+ GUI as a whole including the Opus+ library itself.


4.4 Testing the Opus+ GUI InstallationThe Opus+ GUI jar is runnable. Normally you can simply double-click the opusgui.jar icon and the GUI should open. However, the first time it is run this should be done from the command line as so:

• Open a terminal• Change into the <OPUSGUI_ROOT_DIR>/bin directory • Run the jar from the command line with the following command:

java -jar opusgui.jar

This opens the initial Opus+ screen which looks something like so:

Meanwhile in the terminal window you should see output similar to the following:

Adrian-Marriotts-MacBook-Pro:bin adrian$ java -jar opusgui.jar

0 [main] INFO root - Opus+ messages: no Log4J properties file supplied. Using basic configuration

1 [main] INFO root - Opus+ messages: setting informational messages only, level=1 (default)

22 [main] INFO opusplus.lib.OpusLib -

22 [main] INFO opusplus.lib.OpusLib - Opus+ reinitialization request: FULL


23 [main] INFO opusplus.core.streams.numberStreams.IntegerStreamBase - Re-seeding all integer streams ...

93 [main] INFO opusplus.lib.OpusLib - Attempting to find Opus+ settings file: /Users/adrian/ajmroot/OPUSGUI-KITS/version-1,0_v0001/bin/OpusPlusSettings.xml

93 [main] ERROR opusplus.lib.OpusLib - Could not find Opus+ settings file: OpusPlusSettings.xml

93 [main] INFO opusplus.lib.OpusLib - Lilypond Cmd String parameter set to: lilypond

93 [main] INFO opusplus.core.utilities.Misc - Searching for executables on $PATH called: lilypond or lilypond.exe

95 [main] INFO opusplus.core.utilities.Misc - Parsing system path:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/usr/X11/bin:/Users/adrian/ajmroot/bin:/usr/local/mysql/bin

95 [main] INFO opusplus.core.utilities.Misc - Found directory: /usr/bin

95 [main] INFO opusplus.core.utilities.Misc - Found directory: /bin

95 [main] INFO opusplus.core.utilities.Misc - Found directory: /usr/sbin

95 [main] INFO opusplus.core.utilities.Misc - Found directory: /sbin

95 [main] INFO opusplus.core.utilities.Misc - Found directory: /usr/local/bin

95 [main] INFO opusplus.core.utilities.Misc - Found directory: /usr/X11/bin

96 [main] INFO opusplus.core.utilities.Misc - Found directory: /Users/adrian/ajmroot/bin

96 [main] INFO opusplus.core.utilities.Misc - Found directory: /usr/local/mysql/bin

96 [main] INFO opusplus.core.utilities.Misc - Getting system path: returning array of directories, size=8

96 [main] INFO opusplus.core.utilities.Misc - Finding executables called: lilypond or lilypond.exe

96 [main] INFO opusplus.core.utilities.Misc - Looking in directory: /usr/bin

109 [main] INFO opusplus.core.utilities.Misc - Looking in directory: /bin

109 [main] INFO opusplus.core.utilities.Misc - Looking in directory: /usr/sbin

112 [main] INFO opusplus.core.utilities.Misc - Looking in directory: /sbin

113 [main] INFO opusplus.core.utilities.Misc - Looking in directory: /usr/local/bin

113 [main] INFO opusplus.core.utilities.Misc - Looking in directory: /usr/X11/bin

115 [main] INFO opusplus.core.utilities.Misc - Looking in directory: /Users/adrian/ajmroot/bin

115 [main] INFO opusplus.core.utilities.Misc - Found executable: /Users/adrian/ajmroot/bin/lilypond

115 [main] INFO opusplus.core.utilities.Misc - Finding executable 'lilypond' on path returning: /Users/adrian/ajmroot/bin/lilypond

115 [main] INFO opusplus.lib.OpusLib - Lilypond executable found on $PATH: /Users/adrian/ajmroot/bin/lilypond

115 [main] INFO opusplus.lib.OpusLib - Saving current parameters to Opus+ settings file.

...

The important point to note is that Opus+ GUI attempts to find a settings file called OpusSettings.xml – failing to find it Opus+ creates it and fills it with 'sensible' default values. It also checks that the LilyPond program is on the $PATH. Opus+


attempts to find this executable by searching all the directories specified in the $PATH environment variable. Some of this processing is shown above in bold [10]. This is why it is important to run the Opus+ GUI from the command line the first time it is used.

Then the Opus+ GUI checks it can find the properties files necessary for internationalization and handling foreign languages [11]. ...

626 [main] INFO opusgui.internationalization.LocaleMgr - Current locale set to: English (United Kingdom)

627 [main] INFO opusgui.internationalization.LocaleMgr - Testing resource bundle: 'Object List Bundle'

627 [main] INFO opusgui.internationalization.LocaleMgr - Well-known key is: OK

628 [main] INFO opusgui.internationalization.LocaleMgr - Testing resource bundle: 'General Text Bundle'


651 [main] INFO opusgui.internationalization.LocaleMgr - Testing resource bundle: 'Help Text Bundle'


2926 [main] INFO opusgui.Main - Opus+ Neos GUI started


2929 [main] INFO opusplus.lib.OpusLib - Purpose: Opus+ Machine Composition, Version: 1.0, Release Date: 9th May 2011, Author: Adrian Marriott. Copyright (c) 2005, 2006, 2007, 2008, 2009, 2010, 2011 Adrian Marriott. All Rights Reserved.

2940 [main] INFO opusplus.lib.OpusLib - Started: 15-06-11 06:35:40

2941 [main] INFO opusplus.lib.OpusLib - Arguments: None

2942 [main] INFO opusplus.lib.OpusLib - Current working dir: /Users/adrian/ajmroot/OPUSGUI-KITS/version-1,0_v0001/bin

2942 [main] INFO opusplus.lib.OpusLib - PATH=/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/usr/X11/bin:/Users/adrian/ajmroot/bin:/usr/local/mysql/bin


2944 [main] INFO opusplus.lib.OpusLib - Java VM Vendor: Apple Inc.

2944 [main] INFO opusplus.lib.OpusLib - Java VM Details: Java HotSpot(TM) 64-Bit Server VM 14.1-b02-90 mixed mode

2945 [main] INFO opusplus.lib.OpusLib - Java Runtime: Java(TM) SE Runtime Environment 1.6.0_15-b03-219

2945 [main] INFO opusplus.lib.OpusLib - Java Home: /System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home

2946 [main] INFO opusplus.lib.OpusLib - Java Library Path: .:/Library/Java/Extensions:/System/Library/Java/Extensions:/usr/lib/java

2954 [main] INFO opusplus.lib.OpusLib - CLASSPATH: opusgui.jar


2955 [main] INFO opusgui.Main - Click on any button to run Opus+ ......

10 If LilyPond is not found on the path there are many warning messages printed. There are several ways to fix this. Please refer to the section on Installation Trouble-Shooting in this document.

11 Unfortunately the GUI v1.0 is only available in English.


Finally note that the Opus+ GUI prints out information that can be useful if/when trouble-shooting becomes necessary; particularly the $PATH and $CLASSPATH environment variables - these are highlighted in bold above.

Now complete the Opus+ GUI test by pressing any of the four buttons as instructed [12]. This tests that all the required components are available and work together by creating a random composition. It tests that the java command is working, that LilyPond is accessible and can be invoked from Opus+.

You should see many messages streaming down the Opus+ output screen, and the terminal screen, and then your default browser should automatically open [13]

and display the new composition in a page similar to that shown above. Obviously the composition will be entirely different, but there should be displayed a page showing a PDF score with an embedded MIDI media player icon below, as shown above.

12 The Irish Jig button is probably the best choice here as it runs to completion fastest.13 Sometimes if your web browser is currently minimized it does not automatically show itself, and you will need to maximize it yourself

to view the output.


5 Installation Trouble-ShootingThe most common problem involves Opus+ not finding the LilyPond executable on the $PATH. We discuss several different problems and their solutions below.

5.1 LilyPond Program Not Found If you are using a Windows computer, you must reboot (restart) your computer after installing LilyPond for the lilypond program to automatically appear on your $PATH.

If you are on an Apple Mac computer you have several options:

1. Add the lilypond executable directly to your $PATH yourself. This can be done on a system-wide basis, or on a specific-user-only basis. Both will require changes to shell initialization files, the name of which depends on the type of shell your Mac runs [14]. This approach is only recommended for confident users.

2. Create small script which you locate in your own home directory and add this to your $PATH. The Instructions to do this can be found on the LilyPond website here: http://lilypond.org/macos-x.html

3. Edit the OpusSettings.xml file and enter the absolute path to the LilyPond executable. This is relatively simple and is described below.

So to summarize [15]:

• On Apple Mac we recommend both. It is useful to have LilyPond available from the command line, AND it is best to have the absolute path set in the OpusPlusSettings.xml file so that Opus+ can be run by double-clicking on the JAR file [16].

• On Windows LilyPond is automatically on the $PATH and the OpusPlusSettings.xml file is best left with just the command “lilypond” because the default absolute path contains spaces which cause a LilyPond invocation failure.

14 There are three common ones: bash shell (bash) uses .bashrc, C-shell (csh) uses .cshrc and Bourne shell (sh) uses .profile. You can find out which shell you are using by typing ps at the command prompt. On my machine I see the following which shows I'm running the bash shell:

Adrian-Marriotts-MacBook-Pro:~ adrian$ ps PID TTY TIME CMD 185 ttys000 0:00.02 -bash

15 We apologise to the Linux community but as of writing we have not had the opportunity to install either LilyPond or Opus+ onto a Linux system. We would be interested in hearing from anyone who does this so we can update this document.

16 See problem description below in section Double-Clicking Opus+ JAR and LilyPond Fails


http://lilypond.org/macos-x.html

5.2 Edit Opus+ Settings Manually

If LilyPond is not automatically available or you are unable to set the $PATH environment variable yourself, then edit the OpusPlusSettings.xml file by hand using an XML editor, or an ASCII editor such as TextEdit, Wordpad, Vi, Vim, Emacs etc. At the bottom of the file you'll see the following:

<OPUSPLUS_SETTINGS

version="2.14.1"

lilypondCmdString="lilypond"

workingDir="./opusWorkArea"

runLilypondAutomatically="true"

lyFileVersioningStrategy="MONOTONIC_FOLLOW_LARGEST"

lyFileVersionNumberWidth="4"

createSingleScore="true"

createSeparateInstrumentScores="false"

barsPerSingleScoreFile="100"

barsPerSeparateInstrumentScoreFile="100"

minimumBarsPerScoreFile="16"

preferBreakScoreFilesAtSectionBoundaries="true"

pfXMLCompressionStrategy="DEFAULT_VALUE_DIFF"

useSystemParameterXMLReference="false"

saveParameterFramesToFile="true"

vpToPFReferenceStrategy="EACH_VP_HAS_OWN_COPY"

infiniteLoopTimeout="120"

retryPause="10"

maxRetries="8"

generateExampleJavaCode="true"

javaFileVersioningStrategy="OVERWRITE"

/>

Enter the full path to the LilyPond executable between the quotes for the line in bold above; for example on my system it is:

lilypondCmdString="/Programs/lilypond/Lilypond.app/Contents/Resources/bin/lilypond"

Please note that absolute path names which contain spaces will not operate correctly with Opus+ - even if they are double quoted as is the common work-around [17].

For help to find the LilyPond executable on your system see below.

17 For example if LilyPond has been installed in its default location on a Windows machine the full path to the LilyPond executable contains a space in one or more of the directory names. This will not work when written directly into OpusPlusSettings.xml.


5.3 Finding the LilyPond ExecutableOn a Windows PC the LilyPond program you want is called lilypond.exe the location of which is dependent on where you installed LilyPond, but it is recommended by the LilyPond developers that it be installed in its default location somewhere under the Program Files folder i.e.

• C:\Program Files\LilyPond\usr\bin\lilypond.exe

On a Mac it will be located under the Mac application called LilyPond.app. You need to navigate into this application with the browser to find the lilypond executable itself. This is done by 'showing the package contents' as shown below:

… which then opens a window showing the contents of this package. You must then find the lilypond executable itself as shown below:

The path shown in the two diagrams above is:

/Programs/lilypond/Lilypond.app/Contents/Resources/bin/lilypond

… but this can be different on your Apple Mac. Commonly it will be found starting under the /Applications directory.


5.4 Log4J Class Not FoundIf you run either opuslib.jar or opusgui.jar from the command line and see something similar to the following:

Adrian-Marriotts-MacBook-Pro:blah adrian$ java -jar opusplus.jar -pException in thread "main" java.lang.NoClassDefFoundError: org/apache/log4j/Logger

at opusplus.programs.Main.<clinit>(Main.java:46)Caused by: java.lang.ClassNotFoundException: org.apache.log4j.Logger

at java.net.URLClassLoader$1.run(URLClassLoader.java:200)at java.security.AccessController.doPrivileged(Native Method)at java.net.URLClassLoader.findClass(URLClassLoader.java:188)at java.lang.ClassLoader.loadClass(ClassLoader.java:319)at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:330)at java.lang.ClassLoader.loadClass(ClassLoader.java:254)at java.lang.ClassLoader.loadClassInternal(ClassLoader.java:399)... 1 more

This caused because Opus+ uses a 3rd party library called Log4J, and this is included in the Opus+ distribution kit [18] under the lib directory. To properly access this library the Opus+ jar files must be run from the bin directory where it is located by default i.e. from where it was originally unzipped [19].

If the JAR file has been moved, relocate it back into its bin directory. Always run Opus+ jar files from the command line, or by double-clicking them, with them located in their respective bin directories.

5.5 Double-Clicking Opus+ JAR and LilyPond Fails The problem manifests itself on Apple Mac computers: when the Opus+ GUI is run from the command line everything works ok, but when it is started by double-clicking on the JAR file, LilyPond fails to be invoked correctly. The Output Window shows the following error message:

… and the web browser does not show the PDF or MIDI Media icons.

Please note, this can occur even when the LilyPond application is correctly installed, on your $PATH, and can be run from the command line. The simplest solution is to edit the OpusPlusSettings.xml file and include the full path to the LilyPond executable as described in the section Edit Opus+ Settings Manually in this document.

18 The stuff wot you unzipped :-)

19 Referred to elsewhere in this document as either <OPUSLIB_ROOT_DIR>/bin or <OPUSGUI_ROOT_DIR>/bin. Java programmers can rebuild these jar files so they incorporate the Log4J class internally. Whether this contravenes the Log4J license is unclear.


5.6 Web-Browser Shows Blank PageLilyPond runs but when the HTML review file is viewed in the web browser, either automatically or by hand, the display does not show the PDF and MIDI Media widgets – something similar to the following:

This is caused because the HTML Review File references the PDF and MIDI files, and these are missing for some reason. A common reason is that LilyPond failed to be invoked by Opus+ and so, although the .ly file and the .html files have been created, the .pdf and .midi files have not. This can also occur if you have moved the PDF and MIDI files into another directory.

5.7 Further Help and Information If you still have difficulty please refer first to the LilyPond website and/or the Opus+ website and examine things like FAQs etc. As a last resort please feel free to send email regarding any Opus+ issues to:

• [email protected]

Good luck, and we hope you enjoy using Opus+ !!



opus plus installation guide v1.0

Documents