Merge pull request #4 from onera/testSonatypePublish

New stable version with better package organization, updated copyright, PR template, enhancer README.md and contributing.md

.github/pull_request_template.md

@@ -0,0 +1,52 @@
+## Description
+
+Please indicate whether this pull request [adds/removes/fixes/replaces] the [feature/bug/etc]. 
+
+## What type of pull request is this? (check all applicable)
+
+- [ ] Feature
+- [ ] Bug Fix
+- [ ] Documentation Update
+- [ ] Style
+- [ ] Code Refactor
+- [ ] Performance Improvements
+- [ ] Test
+- [ ] Build
+- [ ] CI
+- [ ] Chore (Release)
+- [ ] Revert
+
+## Related Tickets & Documents
+
+If possible ensure that you have provided in your commit message the issue id (available [here](https://github.com/onera/pml-analyzer/issues)) this pull request fixes,
+for instance to refer to issue #42 you can do:
+```shell
+git commit -m "solving issue #42 with ..."
+```
+Check [here](https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) for more information
+
+## Added tests?
+
+- [ ] yes
+- [ ] no, because they aren't needed
+- [ ] no, because I need help
+
+## Added to documentation?
+
+- [ ] README.md
+- [ ] doc
+- [ ] no documentation needed
+
+## Do we need to update pml analyzer version?
+
+- [ ] no
+- [ ] the pull request is only a bug fix, need a bug fix version update
+- [ ] the pull request add new features and ensures retro-compatibility, need a feature addition version update
+- [ ] the pull request is not ensuring retro-capatibility, need a major version update 
+- [ ] not sure, I need help
+
+## Is this new version should be released as soon as possible? 
+
+- [ ] yes
+- [ ] no
+- [ ] not sure, I need help

README.md

@@ -1,14 +1,23 @@
 # PML analyzer
 
-The PML analyzer is an open source API providing a simple DSL to build 
-a description of the architecture of your chip based on the PHYLOG Model Language (PML). 
-From this representation a set of safety and interference model templates can be generated to perfom safety and 
+The PML analyzer is an open source API providing a simple DSL to build
+a description of the architecture of your chip based on the PHYLOG Model Language (PML).
+From this representation a set of safety and interference model templates can be generated to perfom safety and
 interference analyses of your platform.
 
 The only dependencies of the PML analyzer are:
 + The Java Runtime Environment version 8 [JRE 1.8](http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html) or newer.
 + The Simple Build Tool [SBT](https://www.scala-sbt.org/)
 
+## Configurations
+
+### build.sbt
+
+To get the version X.Y.Z of pml analyzer simply add the following line to your build.sbt file:
+```scala
+libraryDependencies += "io.github.onera" % "pml_analyzer" % "X.Y.Z"
+```
+
 ## Installing dependencies
 
 ### Java 8
@@ -36,6 +45,13 @@ java -jar -Djava.library.path=yourPath sbt-launch.jar
 # to run a JAR
 java -jar -Djava.library.path=yourPath youJar.jar 
 ```
+### Cecilia
+
+It is possible to export PML models as [CeciliaOCAS](https://satodev.com/nos-produits/cecilia-workshop/) or [OpenAltarica](https://www.openaltarica.fr/docs-downloads/) models and perform automatic analyses or simulation out of these models.
+
+### IDP
+
+It is possible to use [IDP](https://dtai.cs.kuleuven.be/software/idp/try) as an alternative to MONOSAT to perform the interference analyses out of your PML model.
 
 ## Using the PML analyzer
 
@@ -51,14 +67,10 @@ or unlinking entities) are provided in the ``pml.operators``  package.
 Exporters to [yuml](https://yuml.me/diagram) and [graphviz](http://www.graphviz.org/) are provided in the ``pml.exporters`` package.  
 
 The compilation of a PML model can be easily perform with [SBT](https://www.scala-sbt.org/) 
-+ First launch sbt in the project repository (this operation may take some time)
-```sbtshell
- sbt 
+Simply run the following command in the project repository (this operation may take some time)
+```shell
+ sbt runMain pathToYourModel
 ```
-+ Once sbt is ready to receive command launch the compilation and execution of your PML model 
-```sbtshell
- runMain pathToYourModel
- ```
 
 ### Editing a PML Model
 
@@ -75,8 +87,8 @@ your modeling activity.
 
 To edit PML model with Intellij please follow the installation steps given by [JetBrain](https://www.jetbrains.com).
 The installation can be made for any platform and does not require any administrator privilege.
-Once the Intellij is installed please download the Scala and SBT Executor plugins.
-
+Once the Intellij IDE is installed please download the Scala and SBT Executor plugins.
+More information are available on the  [Intellij Scala 3 support guide](https://dotty.epfl.ch/3.0.0/docs/usage/ide-support.html)
 #### Creating a project with Intellij
 
 The build specifications and project structure are provided with the PML source code.
@@ -101,7 +113,7 @@ dynamic library of monosat by editing your run configuration and adding to VM op
 
 #### Argumentation patterns
 
-The justification patterns considered for the CAST32-A are provided in the ``views.patterns`` package. 
+The justification patterns considered for the AMC20-193 (former CAST32-A) are provided in the ``views.patterns`` package. 
 These patterns  can be used as a starting point to start your argumentation activity.
 
 To compile and run the PHYLOG patterns example please enter the following commands:
@@ -116,16 +128,16 @@ your modeling activity.
 
 To compile and run the Keystone example please enter the following commands:
 ```sbtshell
- sbt runMain pml.examples.keystone.SimpleKeystoneExport
+ sbt runMain pml.examples.simpleKeystone.SimpleKeystoneExport
 ```
 
 #### Analysis
 For each view (interference, patterns and dependability) examples are provided in the dedicated ``views.X.examples``.
 These benchmarks can be used as a starting point to
 your analysis activity. For instance, we can carry out the interference analysis of the Keystone platform with
  ```sbtshell
- # example of a PML model where an IDP interference model is generated
- sbt runMain views.interference.examples.SimpleKeystoneInterferenceGeneration
+ # example of a PML model where a MONOSAT based interference identification is performed
+ sbt runMain views.interference.examples.simpleKeystone.SimpleKeystoneInterferenceGeneration
  ```
 
 If the tool is running on a Unix System you can use the Makefile to compile the DOT and LaTeX generated file:
@@ -140,7 +152,7 @@ make patterns
 make png
 ``` 
 
-### Packaging
+### Package your model
 
 All projects can be packaged into a single FATJAR containing all non-native dependencies.
 The available projects can be obtained by running:
@@ -157,12 +169,4 @@ The resulting FATJAR will be produced in projectName/target/scala3.2.2
 If your system contains a docker engine, you can build a docker image by running the following command:
 ```sbtshell
  sbt docker
-```
-
-### External tools
-
-The PML modeling does not rely on any external dependency. Nevertheless, it is possible
-to connect some backend analysis tools to directly perform analyses out of your PML model:
-  * for interference analysis: [IDP](https://dtai.cs.kuleuven.be/software/idp/try) or [Monosat](https://github.com/sambayless/monosat)
-  * for the safety analysis: [CeciliaOCAS]() or [OpenAltarica](https://www.openaltarica.fr/docs-downloads/) 
-
+```

build.sbt

@@ -87,8 +87,18 @@ lazy val assemblySettings = Seq(
 
 //Definition of the common settings for the projects (ie the scala version, compilation options and library resolvers)
 lazy val commonSettings = Seq(
-  organization := "onera",
-  version := "1.0.0",
+  organization := "io.github.onera",
+  homepage := Some(url("https://github.com/onera/pml-analyzer")),
+  scmInfo := Some(ScmInfo(url("https://github.com/onera/pml-analyzer"), "[email protected]:onera/pml-analyzer.git")) ,
+  developers := List (Developer("kevin-delmas", "kevin-delmas", "[email protected]", url("https://www.onera.fr/en/staff/kevin-delmas"))) ,
+  licenses +=("LGPL-2.1", url("https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html")) ,
+  publishMavenStyle := true,
+  credentials += Credentials(Path.userHome / ".sbt" / "sonatype_credentials"),
+  pomIncludeRepository := { _ => false },
+  crossPaths := false,
+  publishTo :=  Some("releases" at "https://s01.oss.sonatype.org/" + "service/local/staging/deploy/maven2"),
+  publishMavenStyle := true,
+  version := "1.0.1",
   scalaVersion := "3.2.2",
   sbtVersion := "1.8.2",
   scalacOptions := Seq("-unchecked", "-deprecation", "-feature"),

contributing.md

@@ -0,0 +1,90 @@
+# Contributing
+
+When contributing to this repository, please first discuss the change you wish to make via issue,
+email, or any other method with the owners of this repository before making a change.
+
+## Pull Request Process
+
+1. Fork, then clone the repo:
+```shell 
+git clone [email protected]:your-username/pml-analyzer.git 
+```
+2. See README.md to set up your machine.
+3. Make sure the tests pass:
+```shell
+sbt test 
+```
+4. Make your change and please follow the [Scala 3 coding and documentation style guide](https://docs.scala-lang.org/style/). 
+5. Add tests for your change. Make the tests pass:
+```shell
+sbt test 
+```
+6. Update the README.md with details of changes to the API or the analysis process.
+7. Increase the version numbers in any examples files, the README.md and the build.sbt to the new version that this
+   Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/).
+```scala
+//Change version in build.sbt
+version := "X.Y.Z"
+```
+8. You may merge the Pull Request in once you have the sign-off of two other developers, or if you
+   do not have permission to do that, you may request the second reviewer to merge it for you.
+
+## Code of Conduct
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+### Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+### Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+### Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+### Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

doc/_assets/text/rootContent.txt

@@ -0,0 +1,4 @@
+The PML analyzer is an open source API providing a simple DSL to build
+a description of the architecture of your chip based on the PHYLOG Model Language (PML).
+From this representation a set of safety and interference model templates can be generated to perfom safety and
+interference analyses of your platform.

doc/_docs/example/simpleKeystone/export.md

@@ -0,0 +1,35 @@
+---
+layout: doc-page
+title: "Exports"
+---
+
+### Configured platform
+
+The file src/main/scala/pml/examples/simple/SimpleExport shows how graphical exports are produced (stored in export folder)
+from a platform:
+* graph of used SW and HW
+* graph of used services per application
+* table of transaction
+* table of data
+* table of SW allocation to HW
+* table of component activation
+* table of SW usage
+* routing table
+* transfert table
+
+### Interference analysis
+
+The file src/main/scala/views/interference/examples/SimpleInterferenceGeneration shows how interference analysis can be performed
+on a configured platform. The generated files are stored in analysis folder:
+* computation of n-itf
+* computation of n-free
+* computation of n-channels
+
+As an example the following interference is identified as a 3-itf in the first time slice:
+
+< app1_wr_d2 || app21_wr_d1 || app4_wr_input_d >
+
+<img alt="interference_channel"  width=100% src="images/simpleKeystone/interference.PNG" title="Footprint and interference channel (identified by the two circles)"/>
+
+Figure 5: Example of footprint and interference channel (identified by the two circles) 
+

doc/_docs/example/simpleKeystone/index.md

@@ -0,0 +1,12 @@
+---
+layout: index
+---
+
+This section provides a simple yet comprehensive example of a processor PML model composed of:
+* two cores,
+* one DMA (Direct Access Memory),
+* one Ethernet device,
+* one DDR and SRAM memory,
+* one SPI controller,
+* an interrupt controller (MPIC),
+* and a set of configuration registers reachable through a specific configuration bus.

doc/_docs/example/simpleKeystone/library.md

@@ -0,0 +1,33 @@
+---
+layout: doc-page
+title: "Transaction library"
+---
+
+The application layer is composed of five tasks:
+* app4 is an asynchronous microcode running on the Ethernet component.
+  Each time an Ethernet frame arrives, it transfers the payload of the frame to SRAM (transaction t41).
+* app21 and app22 are two periodic tasks running core1.
+* * At each period app21 reads the last Ethernet message from SRAM,
+    makes some input treatments on the message, and makes it available for app1 in DDR.
+* * Similarly, at each period app22 reads output data of app1 from DDR. It transforms them into SPI frames.
+    The frames are then store in SRAM. And finally app22 wakes up the DMA (app3)
+    by writing the address of the SPI frames into the DMA registers.
+* app3 is a microcode running on DMA. When woke up, app3 reads the SPI frame from
+  SRAM and transfers it to SPI.
+* app1 is an asynchronous applicative task running on core0 and activated each time a external interrupt arrives.
+  It begins by reading the interrupt code from MPIC (transaction t11).
+  It reads its input data from DDR (transaction t12).
+  Then it runs using the internal cache of core0 (transaction t13).
+  And finally it stores its output data in DDR (transaction t14).
+
+The transactions are drawn in Figure 2.
+
+<img alt="transaction" src="images/simpleKeystone/transactions.PNG" width=100% title="Transactions of app1, app21 app22, app3,and app4"/>
+
+Figure 2: Transactions of app1, app21 app22, app3,and app4.
+
+By design, app22 and app3 do not run simultaneously, as app22 wakes up app3 at the end of its execution.
+
+PML Encoding is provided in src/main/scala/pml/examples/simple/SimpleTransactionLibrary.scala
+
+In this example all defined transaction are used, the configuration of the library is provided in src/main/scala/examples/simple/SimpleLibraryConfiguration