There are two ways to use PHDL. The first way is with the command prompt (Option 1) and the second way is with an Eclipse IDE Plugin, (Option 2). We encourage new users to start with the plugin (Option 2). IDE plugins provide many useful features such as syntax highlighting, content assist, and automatic code completion that greatly reduce the learning curve with any new language.
Installing the plugin involves a few more steps through the use
of eclipse update sites. Due to the nature of open source
projects, and in particular the Xtext project which PHDL
IDE is built around, the quantity of these steps is expected to
decrease in future PHDL releases.
Option 1 ― Install PHDL Command-Line Compiler and Translator
You can run the PHDL compiler as a stand-alone tool without any eclipse support if you would like.
- Install Java 1.6 or higher here.
- Download the jar from here and save on your disk with the name "phdlcomp.jar".
- Run the jar from a command line prompt like this:
$ java -jar phdlcomp.jar -src <srcFolder>
where <srcFolder> contains all relevant PHDL source files for the design. The output will be generated in the folder of the same name as the source folder appended with "-gen". The command-line compiler will soon have support for advanced user switches and flags to change this default behavior.
(The above assumes that "." is on your classpath variable.)
Note: Also use the -? flag for help on more command-line flag options.
Option 2 ― Install the PHDL IDE Eclipse Plugin 2.1 (Beta) from the update site:
- Install Java: Eclipse is a java-based application,
and requires a suitable runtime environment to run. Regardless
of your operating system, you will need a Java Virtual Machine
(JVM). You may fulfill the requirement for installing a JVM by
installing a Java Runtime Environment (JRE), or Java Development
Kit (JDK). A popular source is Oracle, found here.
Install java 1.6 or higher.
- Install Eclipse: If you do not have a working
installation of Eclipse INDIGO running, download and
install one from here.
Select your operating system on the right hand side, and choose
the Eclipse IDE for Java developers on the following page.
Download and save the archive to your machine.
- For Windows: extract the contents of the archive. For example, extract to: C:\Program Files\eclipse.
- For Mac/Linux: after downloading, untar the file you get. The result will be an "Eclipse" folder which you simply copy instact into the Applications folder. Inside that folder is an Eclipse application icon which, when clicked, will open Eclipse. However, hold off on running it until you have modified your eclipse.ini file in the next step.
- Modify The "eclipse.ini" File: PHDL IDE is built
around the Xtext framework. Xtext requires a bit more resources
from Eclipse than are available by default. Therefore, navigate
to the installation location of Eclipse, and open the eclipse.ini
file in a text editor. Add the arguments:
-XX:MaxPermSize=256m
-Xmx512m
after the -vmargs line. If -vmargs is not present in the file, add it and then add those two arguments after it. Depending on your platform and where you installed eclipse, the location of eclipse.ini may be:- For Windows: the file will be located at C:\Program Files\eclipse\eclipse.ini
- For Mac: find where your eclipse is installed. On a typical machine it might be in: /Applications/eclipse. On that machine, the eclipse.ini file would be at: /Applications/eclipse/Eclipse.app/Contents/MacOS. The Mac Finder won't let you look inside a package directory (which Eclipse.app is). To get inside, right click the Eclipse icon inside /Applications/eclipse and choose "Show Package Contents". Alternatively, you can edit this file via the Terminal application and 'vi'.
- For Linux: the file will be located in /eclipse/
- Run Eclipse for the first time: The first time you run
Eclipse it will ask you to select or create a workspace area.
This is where Eclipse keeps all your projects. If you have run
Eclipse before, the existing workspace will work just fine.
Otherwise, give it a directory name to keep your projects in.
- Install Xtext Dependencies: Start Eclipse, and wait
for "building workspace" to complete if running. From the menu
bar, choose:
Help -> Install New Software...
In the window that pops up, click Add... and copy and paste the following update site into the location: http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/
Give the location a name (Xtext) for the update site. Click OK. (If the OK button is not clickable, it means you already have an update site with that name or location, or there is a problem with your Eclipse installation.) The list may take a while to populate.
From the list, select Xtext2.2.1 (way down at the bottom). Proceed with the rest of the installation by clicking Next and agree to the terms, conditions and licensing. Complete the wizard by clicking on the Next button until you can click Finish. The installation may ask questions regarding unsigned content, and to restart eclipse when finished. Click yes to these when prompted. It is important not to interrupt Eclipse during the installation process!
- Install PHDL IDE Plugin: Repeat step 5 with the
following update site:
http://phdl.sourceforge.net/update
Enter a name (PHDL) for the update site and click OK. Wait for the list to populate and choose the PHDL IDE category. Proceed through the installation prompts exactly as in step 5.
- Install optional content assist template file: In
future releases of this plugin, this template file will be
automatically included in the installation process. This
template file will make smart proposals for PHDL constructs
based on the context of where the proposals are queried. Once
the file has been imported, use CTRL + SPACE to activate
template proposals anywhere in your source code.
The template file can be found here for Mac users and here, for non Mac users. You should take this file and put it on your local machine somewhere. To add it manually to the beta release you need to set it in the Eclipse preferences.
On Windows do this:
choose Window -> Preferences -> Phdl -> Templates -> Import and import the template file found.
On a Mac, open Preferences (CMD-,) and then open the PHDL item and and select Templates. As of writing this, the template called "Template to concatenate another connection" will not import on a Mac, and has been removed from the Mac template file.
- Using the Plugin: Congratulations! The PHDL IDE
Eclipse plugin is now installed, and you may begin developing in
PHDL. Please refer to the quickstart guide and our
tutorial
to get started!
- If you prefer to watch a video of these steps, click on the
following video link below. Note: There is no sound. The
directions are provided visually, or with annotated pop-ups as
needed.