Merge pull request #17 from stffrdhrn/master

Fixups for documentation + add defaults for yosys synth

README.md

@@ -51,6 +51,16 @@ Builds a pipeline for OpenRISC projects.
 Out of the box it configures:
 - Pulls Docker images for `librecores-ci-openrisc`
 - Executes jobs in parallel inside Docker images
+- Each `job` invocation will run the `.travis/test.sh` script in the module directory
+
+#### Parameters
+
+- job - invokes a new job, the sub-parameters are:
+ - job - the value of the `JOB` env var that will be exported to `.travis/test.sh`
+ - sim - (optional) the value of the `SIM` env var that will be exported to `.travis/test.sh`
+ - pipeline - (optional) the value of the `PIPELINE` env var that will be exported to `.travis/test.sh`
+ - expectedFailures - (optional) the value of the `EXPECTED_FAILURES` env var that will be exported to `.travis/test.sh`
+ - extraCoreArgs - (optional) the value of the `EXTRA_CORE_ARGS` env var that will be exported to `.travis/test.sh`
 
 #### Example
 
@@ -60,27 +70,41 @@ This snippet is from the Jenkins pipeline for [mor1kx](https://github.com/openri
 @Library('librecoresci') _
 
 openriscPipeline {
-        job('verilator') {
-            job 'verilator'
-        }
+    job('verilator') {
+        job 'verilator'
+    }
 
-        job('testing-1') {
-            job 'or1k-tests'
-            sim 'icarus'
-            pipeline 'CAPPUCCINO'
-            expectedFailures 'or1k-cy'
-        }
+    job('testing-1') {
+        job 'or1k-tests'
+        sim 'icarus'
+        pipeline 'CAPPUCCINO'
+        expectedFailures 'or1k-cy'
+    }
 }
 ```
 ### fusesoc
 
-Builds a step for a generic FuseSoC invocation.
+Builds a step for generic FuseSoC invocation.
 
 - Chooses a base docker image with FuseSoC
 - Adds library to FuseSoC
 - Runs FuseSoC step
 - Runs arbitrary shell commands in this step
 
+#### Parameters
+
+- image - name of the docker image to execute within
+- library - name of a FuseSoC library to include into the build, multiple
+  libraries may be specified
+- run - a FuseSoC target to run the argument, `some_core` below, is the core to
+    run. `run()` can be specified multiple times to execute multiple fusesoc
+    builds. The available parameters are:
+  - target - the FuseSoC target to run, the `--target` argument to fusesoc
+  - tool - the FuseSoC tool to run, the `--tool` argument to fusesoc
+  - backendArgs - additional args to provide to fusesoc
+- shell - a shell command to run, multiple invokations can be specified, all 
+  will be run after FuseSoC
+
 #### Example
 
 ```groovy
@@ -107,10 +131,16 @@ pipeline {
 
 Build a step for [Yosys Synthesis](http://www.clifford.at/yosys/) for monitoring resource usage statistics and publish on Jenkins.
 
-- Generalised Yosys Synthesis 
-- Can be configured for various hardware projects 
+- Generalised Yosys Synthesis
+- Can be configured for various hardware projects
 - Simple declarative call which requires parameters `core`, `target`, `logpath`
-- Can be modified and extend to include more paramaters in future.
+- Can be modified and extend to include more parameters in future.
+
+#### Parameters
+
+ - core - the fusesoc core to run
+ - target - the fusesoc target to run yosys synthesis, the default is "synth"
+ - logPath - the location of the `yosys.log` file, the default is "build/${core}_*/${target}-*/yosys.log"
 
 #### Example 
 
@@ -123,10 +153,10 @@ pipeline {
         stage('yosys') {
             steps {
                 yosysSynthesisReport {
-					core 'mor1kx'
-					target 'synth'
-					logPath 'build/mor1kx_5.0-r3/synth-icestorm/yosys.log'
-				}
+                    core 'mor1kx'
+                    target 'synth'
+                    logPath 'build/mor1kx_5.0-r3/synth-icestorm/yosys.log'
+                }
             }
         }
     }

src/org/librecores/fusesoc/YosysJobSpec.groovy

@@ -2,8 +2,8 @@ package org.librecores.fusesoc
 
 class YosysJobSpec {
     String core
+    String target = "synth"
     String logPath
-    String target
 
     def core(String value) {
         this.core = value
@@ -16,4 +16,12 @@ class YosysJobSpec {
     def target(String value) {
         this.target = value
     }
+
+    /**
+     * Expand defaults if required.
+     */
+    void build() {
+        this.logPath = this.logPath ?: "build/${core}_*/${target}-*/yosys.log"
+    }
+
 }

vars/openriscPipeline.groovy

@@ -20,8 +20,8 @@ def buildStage(jobConfig) {
 
     def envVars = "-e \"JOB=${job}\" " +
             "-e \"SIM=${sim}\" " +
-            "-e \"PIPELINE=${pipeline}\"" +
-            " -e \"EXPECTED_FAILURES=${expectedFailures}\" " +
+            "-e \"PIPELINE=${pipeline}\" " +
+            "-e \"EXPECTED_FAILURES=${expectedFailures}\" " +
             "-e \"EXTRA_CORE_ARGS=${extraCoreArgs}\""
 
     return {

vars/yosysSynthesisReport.groovy

@@ -8,6 +8,8 @@ def call(@DelegatesTo(strategy = Closure.DELEGATE_ONLY, value = YosysJobSpec) Cl
     cl.delegate = jobSpec
     cl()
 
+    jobSpec.build()
+
     fusesoc {
         image 'librecores/librecores-ci:0.5.0'
         library jobSpec.core, '/src'