search

lsds / sgx-lkl

SGX-LKL Library OS for running Linux applications inside of Intel SGX enclaves
MIT License
255 stars 89 forks source link

Simplify samples #332

Open letmaik opened 4 years ago

letmaik commented 4 years ago

Samples are currently a bit hard to understand because they use makefiles and have sparse READMEs.

The idea is to simplify the samples as much as possible to make them easier to digest for humans. The README of each sample should be re-written to be more verbose, more like tutorials, and list all commands explicitly without relying on automation (except using SGX-LKL tooling). ~At the same time they are still runnable unattended by having two scripts build.sh and run.sh in each sample folder which we may use as part of crash tests in CI.~ EDIT: CI automation will be looked at later.

prp commented 4 years ago

Yes, I agree that the README should show all the commands, so a user understands how they are run. Given that, we can even dispense with having scripts at all?

letmaik commented 4 years ago

Scripts are needed to test samples in CI. We don't need to reference the scripts in the READMEs, but they are important. Except if every sample uses the exact same commands of course, but I don't have a good overview yet if that's the case.

prp commented 4 years ago

As mentioned before, I would separate samples from tests because they serve very different purposes: samples are for human consumption, but tests need to integrate with the CI set-up.

letmaik commented 4 years ago

I'm sorry, but I disagree. Testable samples/documentation is a thing, and we should do it as much as possible.

prp commented 4 years ago

I agree with using the CI to test both the tests and the samples, but not with merging both into one.

letmaik commented 4 years ago

Merging?

prp commented 4 years ago

Merging?

Not having separate directories (which is not what you suggest :-)

letmaik commented 4 years ago

I've merged the first sample rewrite in #333 and am now looking at the other samples. I think we need to rethink them completely, even the hello world sample is not right in my opinion. It should be something much simpler not involving compilation of C code. In general I also don't want to replicate tests. I think it would be much nicer to have samples which focus on certain tooling tasks or goals. Including specific samples for certain application workloads is ok but only if there is something special about them, e.g. in terms of the configuration or Dockerfile. @prp What do you think?

prp commented 4 years ago

I've merged the first sample rewrite in #333 and am now looking at the other samples. I think we need to rethink them completely, even the hello world sample is not right in my opinion. It should be something much simpler not involving compilation of C code. In general I also don't want to replicate tests. I think it would be much nicer to have samples which focus on certain tooling tasks or goals. Including specific samples for certain application workloads is ok but only if there is something special about them, e.g. in terms of the configuration or Dockerfile. @prp What do you think?

I guess that we need to make a decision if we want the samples only to be "lift-and-shift" deployments based on Dockerfiles or also show more developer-oriented workflows, e.g. where an application is cross-compiled for musl.

I think that it's fine if there is overlap between the used SGX-LKL features among the samples. When a user wants to understand "does SGX-LKL support an important application workload X", they will first see if there is a sample showing that application. It would be good if we had 10 samples that covered the most important open-source applications that people may want to run in enclaves.

letmaik commented 4 years ago

I guess that we need to make a decision if we want the samples only to be "lift-and-shift" deployments based on Dockerfiles or also show more developer-oriented workflows, e.g. where an application is cross-compiled for musl.

I don't understand what "developer-oriented workflow" really means. The default assumption should be that SGX-LKL is installed, and in that case there is no musl cross-compiler available. I don't see why you need to support cross-compiling anyway if you can build your app inside a Docker image from an alpine base image. Am I missing something?

I agree on overlap between samples.

letmaik commented 4 years ago

I guess that we need to make a decision if we want the samples only to be "lift-and-shift" deployments based on Dockerfiles or also show more developer-oriented workflows, e.g. where an application is cross-compiled for musl.

I don't understand what "developer-oriented workflow" really means. The default assumption should be that SGX-LKL is installed, and in that case there is no musl cross-compiler available. I don't see why you need to support cross-compiling anyway if you can build your app inside a Docker image from an alpine base image. Am I missing something?

Following from https://github.com/lsds/sgx-lkl/issues/368#issuecomment-641861361 I now agree that it makes sense to have examples for different kinds of deployment/usage scenarios, including non-Docker. As long as it's easy to find the way through the docs and samples to the suggested end-user flow (using Docker) it should be fine. Priority should be on the end-user flows first.