github.com/emc-advanced-dev/unik@v0.0.0-20190717152701-a58d3e8e33b7/docs/compilers/osv.md (about)

     1  # OSv Unikernels
     2  
     3  UniK supports [OSv](http://osv.io) unikernel creation.
     4  OSv is somewhat different from other unikernel implementations.
     5  Firstly, it can run application written in any programming language.
     6  And secondly, due to some specifics in OSv kernel implementation, it can make use of
     7  precompiled application packages that are stored in public repository.
     8  In other words, in OSv you can not only run your own application (e.g. your NodeJS server),
     9  but also arbitrary application from the public repository (e.g. MySQL).
    10  
    11  UniK provides support for three languages: nodejs, java and native.
    12  Native language refers to C/C++ compiled code that can be either your own
    13  either from the remote repository.
    14  
    15  Please note that UniK **does not** compile your application code (except in a case of Java,
    16  but this functionality is scheduled for removal). Basically, all that it can do for you
    17  is to upload your files to the unikernel.
    18  
    19  ---
    20  
    21  ## Java
    22  
    23  Compiling Java on the OSv platform requires the following parameters be met:
    24  * Project compiles to Java version 1.8 or earlier
    25  * A `manifest.yaml` file in the root directory of the project specifying the following information:
    26    * An optional build command for unpackaged sources (required if the project is not already packaged as a `.jar` or `.war` file).
    27    * The name of the project artifact
    28    * An optional list of properties (normally set with the `-Dproperty=value` in java) to pass to the application
    29    * See the [example java project](../examples/example_osv_java_project) or the [example java servlet](../examples/example_osv_java_project) for an example.
    30  * Either:
    31    * Project packaged as a fat `.jar` file or `.war` file *or*
    32    * Project uses **Gradle** or **Maven** and able to be built as a fat `.jar` or `.war`
    33  
    34  ## Node.js
    35  
    36  [NodeJS example](../examples/example-osv-nodejs)
    37  
    38  It's trivial to deploy your Node.js application into unikernel. First you must collect all
    39  external npm libraries with:
    40  ```
    41  $ cd $PROJECT_ROOT
    42  $ npm install
    43  ```
    44  Then you can consult built-in documentation to see what configuration files are needed by UniK:
    45  ```
    46  $ unik describe-compiler
    47     --base osv
    48     --language nodejs
    49     --provider [qemu|openstack]
    50  
    51  OVERVIEW
    52  Language "nodejs" allows you to run your NodeJS 4.4.5 application.
    53  Please provide meta/run.yaml file where you describe your project
    54  structure. See below for more details.
    55  
    56  HOW TO PREPARE APPLICATION
    57  Install all libraries using `npm install`.
    58  
    59  CONFIGURATION FILES
    60  ------ /meta/run.yaml ------
    61  config_set:
    62     conf1:
    63        main: <relative-path-to-your-entrypoint>
    64  config_set_default: conf1
    65  
    66  ------ /manifest.yaml ------
    67  image_size: "10GB"  # logical image size
    68  ```
    69  
    70  As you can see above, you need to create folder `meta` inside your application and create
    71  file `run.yaml` in it. In this file you specify where your entrypoint file is. For example, if your
    72  entrypoint file is `server.js`, then the final content of `meta/run.yaml` would be:
    73  ```
    74  config_set:
    75     conf1:
    76        main: /server.js
    77  config_set_default: conf1
    78  ```
    79  Optionally, you can create file `manifest.yaml` directly inside your project root directory
    80  where you specify some additional parameters. Parameter `image_size` specifies filesystem size
    81  of the created unikenrel.
    82  
    83  ### Build command
    84  Use this command to build unikernel with your NodeJS application:
    85  ```
    86  $ cd $PROJECT_ROOT
    87  $ unik build
    88     --name myImg
    89     --path ./
    90     --base osv
    91     --language nodejs
    92     --provider [qemu|openstack]
    93  ```
    94  
    95  ## Native
    96  
    97  [C/C++ example](../examples/example-osv-mysql)
    98  
    99  Native runtime can be used either for running your C/C++ application or for running
   100  arbitrary precompiled application that exists in public repository (these are called
   101  application packages).
   102  
   103  ### Running application package
   104  Consult built-in documentation to see what configuration files are needed by UniK:
   105  ```
   106  $ unik describe-compiler
   107     --base osv
   108     --language native
   109     --provider [qemu|openstack]
   110  
   111  OVERVIEW
   112  Language "native" allows you to either:
   113  a) run precompiled package from the remote repository
   114  b) run your own binary code
   115  c) combination of (a) and (b)
   116  In case you intend to use packages from the remote repository, please provide
   117  meta/package.yaml where you list desired packages.
   118  In any case (i.e. (a), (b), (c)) you need to provide meta/run.yaml. See below for
   119  more details.
   120  
   121  Additionally, please consult Capstan documentation:
   122  https://github.com/mikelangelo-project/capstan/blob/master/Documentation/ConfigurationFiles.md
   123  
   124  HOW TO PREPARE APPLICATION
   125  (this is only needed if you want to run your own C/C++ application)
   126  Compile your application into relocatable shared-object (a file normally
   127  given a ".so" extension) that is PIC (position independent code).
   128  
   129  CONFIGURATION FILES
   130  ------ /manifest.yaml ------
   131  image_size: "10GB"  # logical image size
   132  
   133  ------ /meta/run.yaml ------
   134  config_set:
   135     conf1:
   136        bootcmd: <boot-command-that-starts-application>
   137  config_set_default: conf1
   138  
   139  ------ /meta/package.yaml ------
   140  title: <your-unikernel-title>
   141  name: <your-unikernel-name>
   142  author: <your-name>
   143  require:
   144    - <first-required-package-title>
   145    - <second-required-package-title>
   146    # ...
   147  
   148  OTHER
   149  Below please find a list of packages in remote repository:
   150  
   151  eu.mikelangelo-project.app.hadoop-hdfs
   152  eu.mikelangelo-project.app.mysql-5.6.21
   153  eu.mikelangelo-project.erlang
   154  eu.mikelangelo-project.ompi
   155  eu.mikelangelo-project.openfoam.core
   156  eu.mikelangelo-project.openfoam.pimplefoam
   157  eu.mikelangelo-project.openfoam.pisofoam
   158  eu.mikelangelo-project.openfoam.poroussimplefoam
   159  eu.mikelangelo-project.openfoam.potentialfoam
   160  eu.mikelangelo-project.openfoam.rhoporoussimplefoam
   161  eu.mikelangelo-project.openfoam.rhosimplefoam
   162  eu.mikelangelo-project.openfoam.simplefoam
   163  eu.mikelangelo-project.osv.cli
   164  eu.mikelangelo-project.osv.cloud-init
   165  eu.mikelangelo-project.osv.httpserver
   166  eu.mikelangelo-project.osv.nfs
   167  ```
   168  As you can see above, you need to create folder `meta` inside your application and create
   169  file `package.yaml` in it. In this file you specify what application packages do you want to
   170  use. For example, if you want to run MySQL server, then the content of `meta/package.yaml`
   171  would be:
   172  ```
   173  name: my.test
   174  title: My Test
   175  author: Name Surname (name.surname@email.com)
   176  require:
   177   - eu.mikelangelo-project.app.mysql-5.6.21
   178  ```
   179  Furthermore, you need to create file `meta/run.yaml` with the following content:
   180  ```
   181  config_set:
   182     conf1:
   183        bootcmd: /usr/bin/mysqld --datadir=/usr/data --user=root --init-file=/etc/mysql-init.txt
   184  config_set_default: conf1
   185  ```
   186  And there you go, you can build your unikernel.
   187  
   188  ### Build command
   189  Use this command to build unikernel with precompiled application (e.g. MySQL):
   190  ```
   191  $ cd $PROJECT_ROOT
   192  $ unik build
   193     --name myImg
   194     --path ./
   195     --base osv
   196     --language native
   197     --provider [qemu|openstack]
   198  ```
   199