Have gotten a sample project from this site? Here is how to build the project.
Topics
About: UNO (Universal Network Objects)
About: LibreOffice
About: Apache OpenOffice
About: the Java programming language
About: C++
About: C#
About: the Python programming language
About: LibreOffice Basic
About: Apache OpenOffice Basic
About: BeanShell
About: JavaScript
The table of contents of this article
- Starting Context
- Target Context
- Orientation
- Main Body
- 1: The Purport of This Article
- 2: Downloading and Expanding the ZIP File
- 3: Understanding the Structure of the Development Directory
- 4: Building the Project or All the Projects
- 5: Executing the Program
Starting Context
- The reader has built an environment for developing UNO programs in Linux or Microsoft Windows, according to a previous article (for Linux or for Microsoft Windows).
- The reader has a knowledge on basic operations (to use a text editor; to use a terminal) in his or her operating system.
Target Context
- The reader will know how to build any sample project cited in this site.
Orientation
There are some sample projects cited in this site (included in some series: Exploiting LibreOffice or Apache OpenOffice, Let Me Understand C++, and Let Me Understand the Java Programming Language).
Main Body
Stage DirectionHere are Special-Student-7, Objector 7A, and Objector 7B in front of a computer.
1: The Purport of This Article
Special-Student-7
In this article, we will see how to build any sample project that has been gotten from this site.
Objector 7A
What sample project? I haven't gotten any sample project . . .
Special-Student-7
Sir, such sample projects will come in future articles.
Objector 7A
Ah, so I am supposed to have already read a future article. . . . Am I a time traveler?
Special-Student-7
As I do not want to explain how to build a project per future article, the explanation is here in one place in advance.
If you happen to be reading this series sequentially from the beginning, this article may seem meaningless, and you can safely skip this article until you encounter a future article that offers a project.
Objector 7A
Then, I do so.
Stage Direction
Special-Student-7
It is supposed that a development environment is ready according to a previous article (for Linux or for Microsoft Windows).
Objector 7B
I don't have to have my environment "according to your article", do I?
Special-Student-7
Madam, you can have your environment not according to my article of course, but as any of my projects uses Gradle as the build tool, you may have to prepare your own build configuration, and as the project usually depends on my utility projects and the utility projects use some products, you may have to do something about it.
Objector 7B
Being told to "do something about it", there is no other option than installing the products, is there?
Special-Student-7
You can modify the source files to cut out such dependencies if you will.
Objector 7B
Hmm . . .
Special-Student-7
Anyway, I am just trying to spare you some trouble, not enjoining you from doing it in your own way.
2: Downloading and Expanding the ZIP File
Special-Student-7
When an article offers a sample project, the project is included in a ZIP file, which can be download from the article page.
Objector 7A
To where?
Special-Student-7
Oh, I thought you left, sir.
Objector 7A
I have come back from future.
Special-Student-7
Well, anywhere you want to download it to, sir: as it is an archive file which you expand and delete afterwards, the location of the ZIP file does not matter; the location of the expansion matters.
Objector 7A
To where should I expand it, then?
Special-Student-7
Anywhere you want to expand it to, but basically, all the sample ZIP files of this site are meant to be expanded to the same directory, which we will call 'the development directory': there are common-to-projects Gradle build scripts, and we can get done with the only-once configuration, in that way. However, . . .
Objector 7A
"However"?
Special-Student-7
As those common Gradle build scripts will be frequently updated (sometimes incompatibly with prior versions), overwriting those files might break old projects.
Objector 7A
That will be a problem, won't it?
Special-Student-7
In that case, you can download the new versions of the broken projects from this site, or you can opt to create each development directory per sample program, which, of course, necessitates the configuration per development directory.
Objector 7A
Do you mean that you are going to renew ZIP files in that case?
Special-Student-7
That is my intention.
Objector 7A
Why won't you make the updates compatible?
Special-Student-7
Because I sometimes feel the desirability of radically modifying the build scripts.
Objector 7A
. . .
Special-Student-7
That is the same with the utility projects.
Objector 7A
What are "the utility projects"?
Special-Student-7
The sample project usually depends on such projects that are commonly used by most sample projects.
Objector 7A
Does it have to do that?
Special-Student-7
It has to, in order for duplicate code not to be scattered around.
Objector 7A
And are you saying that those common projects may be updated incompatibly?
Special-Student-7
Yes, I am.
Objector 7A
So, overwriting those projects may break old projects . . .
Special-Student-7
In that case, you can download the new versions of the broken projects from this site, or you can opt to create each development directory per sample program.
3: Understanding the Structure of the Development Directory
Special-Student-7
The development directory has some common-to-projects Gradle build scripts.
There is also 'commonVolatileProperties.gradle_Template', which is the template of the configuration file that contains prone-to-be-changed-per-environment settings.
Objector 7A
Do you mean that the settings are common to projects?
Special-Student-7
Yes: the settings are common to projects, although they depend on the environment.
Objector 7A
Ah-ha.
Special-Student-7
You have to change the file name, 'commonVolatileProperties.gradle_Template', to 'commonVolatileProperties.gradle', and configure the settings into the file.
In fact, these are the properties supposed to be set.
| Parameter Name | Value |
|---|---|
| c_javaCompiler | the Java compiler ('c_jdkCompiler' or 'null') (setting it 'null' ignores all the Java source files contained in projects) |
| c_cplusplusCompiler | the C++ compiler ('c_gccCompiler' or 'c_visualStudioCplusplusCompiler' or 'null') (setting it 'null' ignores all the C++ source files contained in projects) |
| c_csharpCompiler | the C# compiler ('c_dotnetCsharpCompiler' or 'null') (setting it 'null' ignores all the C# source files contained in projects) |
| c_pythonCompiler | the Python compiler ('c_theBiasPlanetPythonCompiler' or 'null') (setting it 'null' ignores all the Python source files contained in projects) |
| c_additionalLibrariesDirectoryPath | the directory path of additional libraries, when some projects require such libraries |
| c_javaFxDirectoryPath | the directory path of OpenJFX or 'null' |
| c_javaCheckStyleJarFilePath | the path of the Java Check Style Jar file or 'null' |
| c_javaCheckStyleConfigurationFilePath | the path of the Java Check Style configuration file or 'null' |
| c_visualStudioDirectoryPath | the base directory path of Visual Studio IDE |
| c_visualStudioVersion | the Visual Studio version (a sub directory name under the base directory of Visual Studio IDE) |
| c_windowsSdkDirectoryPath | the base directory path of Windows SDK |
| c_windowsSdkVersion | the Windows SDK version (a sub directory name under the base directory of Windows SDK) |
| c_wxWidgetsDirectoryPath | the base directory path of wxWidgets |
| c_wxWidgetsLibrariesSubDirectoryName | the name of the libraries sub directory under the base directory of wxWidgets |
| c_openSslDirectoryPath | the base directory path of OpenSSL |
| c_officeDirectoryPath | the base directory path of LibreOffice or Apache OpenOffice |
| c_officeAdditionalHeaderFilesBaseDirectoryPath | the base directory path of LibreOffice or Apache OpenOffice additional header files |
The properties used in the file contain these values.
| Property Name | Value |
|---|---|
| c_operatingSystemNamePropertyName | the name of the operating system name Java property |
| c_operatingSystemNameLinux | "Linux" |
| c_projectDirectoryPath | the project directory path |
| c_operatingSystemDirectoriesDelimiter | the directories delimiter ('/' or '\') of the operating system |
Note that anything with its name tailed with "Path" is a 'java.nio.file.Path' instance, not a String instance.
Objector 7B
What does that mean?
Special-Student-7
You cannot set any String instance into 'c_officeDirectoryPath' for example.
Objector 7B
Then, what should I do?
Special-Student-7
Just 'java.nio.file.Paths.get (%the path string%)' will create a 'Path' instance that corresponds to the path string.
Objector 7B
Well, what are those seemingly-meaningless ".toString ()"s doing there?
Special-Student-7
Ah, any expression containing '${}' does not really become a Java String, but a Groovy string, and '.toString ()' makes it a Java String.
Objector 7B
Can't it be a Groovy string?
Special-Student-7
It usually can, but I had been occasionally snared by the difference, so, I have the custom of making it a Java String.
Anyway, what you may want to do is to set 'null's to your unused compilers: while I usually offer my project in multiple programming languages, you will usually want it in a single programming language. Unless you set the 'null's, unnecessary compiling will try to run, failing maybe.
Objector 7B
All right.
Special-Student-7
The 'build.gradle' file in the development directory is the Gradle build script that builds all the projects under the development directory.
Directories right under the development directory (except directories whose names start with '.') are project directories, each of which has the 'build.gradle' file, which is the Gradle project script.
Source files are under the directory, 'source', divided into programming-language-specific directories ('unoIdl', 'java', 'cplusplus', etc.) and the 'resource' directory.
Objector 7A
"'resource' directory"?
Special-Student-7
It contains the Jar manifest file, the UNO extension manifest file and related configuration files, etc.
Objector 7A
Ah-ha.
Special-Student-7
Although there do not exist at first, the 'intermediate' directory and the 'target' directory will be created by the build process. The 'target' directory will contain the target file (for example a UNO extension file if the project is a UNO extension project); the 'intermediate' directory will contain the intermediate files (for example class files if the project includes Java code pieces).
4: Building the Project or All the Projects
Special-Student-7
When we want to build a project, we open a terminal, change the current directory to the project directory, and execute this command, unless we face the Gradle-relentlessly-resolves-symbolic-links problem.
@bash or CMD Source Code
gradle
Objector 7A
What if I face that lengthy-named problem?
Special-Student-7
You can use 'Gradle.sh' in the development directory, instead of 'gradle'.
Objector 7A
Ah.
Special-Student-7
If the project is a UNO extension project, the build process will try to shutdown all the LibreOffice and Apache OpenOffice processes, register the UNO extension, and start a LibreOffice or Apache OpenOffice process.
Objector 7A
I don't want it to do so.
Special-Student-7
Then, please do like this.
@bash or CMD Source Code
gradle i_makeUnoExtensionTask
Then, you need to register the UNO extension by yourself.
Objector 7A
I see.
Special-Student-7
When the project is built, the projects referenced by the project will be automatically built.
We can also build all the projects in the development directory by changing the current directory to the development directory and executing the 'gradle' command.
5: Executing the Program
Special-Student-7
If the project is for executable programs (plural because the project may be for multiple programming languages), one of the programs can be executed like this with the current directory at the project directory, depending on the programming language.
For Java:
@bash or CMD Source Code
gradle i_executeJarTask -Pi_mainClassName="%the main class name%" -Pi_commandLineArguments="%the command line arguments%"
For C++:
@bash or CMD Source Code
gradle i_executeCplusplusExecutableFileTask -Pi_commandLineArguments="%the command line arguments%"
For C#:
@bash or CMD Source Code
gradle i_executeCsharpExecutableFileTask -Pi_commandLineArguments="%the command line arguments%"
For Python:
@bash or CMD Source Code
gradle i_executePythonExecutableFileTask -Pi_mainModuleName="%the main module name%" -Pi_commandLineArguments="%the command line arguments%"
Inside of the 'i_commandLineArguments' property value has to be escaped properly if any double quotation is used there, for example like this.
@bash or CMD Source Code
-Pi_commandLineArguments="\"the 1st argument value\" \"the 2nd argument value\""
