Guides/Folders and Projects
J has two related concepts, folder and project, that help you work with source files. Both are simply references to directories.
Folder
A folder is a name given to a directory. Using folder names instead of full pathnames means that names are typically much shorter, and that it is easy to share code between users with very different directory structures.
The nouns SystemFolders_j_ and UserFolders_j_ have tables of such names, for example:
SystemFolders_j_ +-------+---------------------------------+ |addons |/home/chris/j8/addons | +-------+---------------------------------+ |bin |/home/chris/j8/bin | +-------+---------------------------------+ |break |/home/chris/j8/user/break | +-------+---------------------------------+ |config |/home/chris/dev/user/config/linux| ...
UserFolders_j_ +----+----------------------------------------+ |Grid|/home/chris/deb/base/grid | +----+----------------------------------------+ |R |/home/chris/deb/addons/stats/r | +----+----------------------------------------+ |Ide |/home/chris/deb/addons/gui/gtkide/source| +----+----------------------------------------+ |Main|/home/chris/deb/base8/main | ...
SystemFolders is initialized in the boot up process. UserFolders and additional entries for SystemFolders are given in the configuration file folders.cfg (open with menu Edit|Configure|Folders).
Most of the time, system folders and user folders are used together. The main difference is that the IDE expects J source to be stored under user folders, not under system folders. By convention, system folders have names beginning with lowercase, and user folders have names beginning with upper case.
Verb jpath references the folder tables. It converts strings with folder names preceded with ~ into their full pathname:
jpath &> '~bin/profile.ijs';'~config/folders.cfg';'~R' /home/chris/j8/bin/profile.ijs /home/chris/dev/user/config/linux/folders.cfg /home/chris/deb/addons/stats/r
Dots can be used to reference parent folders:
jpath '~.R/base/random.ijs' /home/chris/deb/addons/stats/base/random.ijs
Project
A project is a subdirectory of a folder that contains a file with extension .jproj with the same name as the directory. For example, if file c:/dev/mywork/grid/grid.jproj exists, then the directory c:/dev/mywork/grid is recognized as a project directory.
Project directories should be subdirectories of folders. For example, if folder name Mywork points to c:/dev/mywork, then this grid project can be referred to as ~Mywork/grid. In the IDE, the ~ prefix is usually omitted.
A project file can be empty, or may contain a simple list of files that define the project source.
Project Scripts
Scripts can have any name, but typically:
- build.ijs is used to assemble the code for the project (if needed)
- run.ijs script is used to run the project, e.g. for testing
These scripts are specially supported by JQt:
- Ctrl+F9 loads build.ijs (if defined) (Use Cmd+F9 on Mac OS X.)
- F9 loads build.ijs (if defined) and then loads run.ijs
For example, you could enter some test code in run.ijs and then press F9 to rebuild the project and run the test.
Project Verbs
Verbs to work with projects are in locale jp. These include:
- readsource_jp_ - this reads all files in a project's source and returns a character string
- writesource_jp_ - this reads the source, and writes to file
Corresponding verbs ending in x delete all comments.
For example, the following reads all source in the project ~Main/project, decomments it, and writes to ~mywork/util/project.ijs. Typically, this command would be given in the project's build script:
writesourcex_jp_ '~Main/project';'~mywork/util/project.ijs'
Example - coins
A simple example is in the demos/coins project (J803 or later).
Install this using Package Manager. Then in the Qt IDE, open project Demos/coins.
Note that the build script will write a script ~Demos/release/coins.ijs.
Use Ctrl-F9 to load the build script and check that the target script has been built. (Use Cmd-F9 on Mac OS X.)
Next use F9 to load the run script.
You can experiment by changing the board definition in the run script (e.g. BOARD=: 1), then press F9 to re-load the run script.
Example - euler
Suppose you are working on Project Euler and want to save each problem in its own script. The default installation has a folder ~Projects that can be used for this:
jpath '~Projects' /home/elmo/j64-806-user/projects
In Jqt, open Project|New, browse to the projects folder (which will default to ~Projects) and enter euler as the project name, i.e. the New Project Folder will be ~Projects/euler. Leave the rest of the form unchanged and press Create.
In the edit window, use Project|Open to open the euler project (if not already open), then File|New to add scripts, e.g. euler1, euler3, euler15 etc.
From now on, you can use Project|Open to select the euler project and navigate to your scripts.
Note that there is nothing special about project files. You could create a project and its scripts with J, for example:
mkdir_j_ '~Projects/euler/'
'' fwrite '~Projects/euler/euler.jproj'
('' fwrite '~Projects/euler/euler' , ":) &> 1 3 15
Addons Source
Most of the addons source uses folders and projects. For example, to see this for the stats/base addon:
1. create a new folder for the addons source somewhere on your machine, say c:\addons.
2. define a folder name Addons to point to this folder. In Jqt, select menu Edit|Configure|Folders and add an entry like:
Addons c:/addons
3. Now create a subfolder stats. In the console:
mkdir c:\addons\stats
4. In the console, change to the stats directory and checkout the stats/base repository into a folder base:
c:\addons\stats> git clone git@github.com:jsoftware/stats_base.git base
5. Load JQt and Ctrl-M to open the editor. Select menu Project|Open (or click the corresponding toolbar button). You should see the Addons folder listed in the first panel. Select it and the stats/base project will be shown in the second panel. Select this to open it in the editor.
Note that addons are in a two-level directory, e.g. stats\base but the corresponding github repo uses an underscore separator, e.g. stats_base. This is because all repos in github are on a single level.