--- COPYING.md | 56 ++++++++++++ README.md | 50 +++++++++++ docs/Clang.md | 5 + docs/CodingStyle.md | 3 + docs/HowItWorks.md | 232 +++++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 346 insertions(+), 0 deletions(-) create mode 100644 COPYING.md create mode 100644 README.md create mode 100644 docs/Clang.md create mode 100644 docs/CodingStyle.md create mode 100644 docs/HowItWorks.md
diff --git a/COPYING.md b/COPYING.md new file mode 100644 index 0000000..5a994cd --- /dev/null +++ b/COPYING.md @@ -0,0 +1,56 @@ +License Information +=================== + +Software in this project is licensed under the MIT License included +belowe. In some cases software in these project has been derived from +other software with its own license. Those special instances are +called out below. + +The Project License +------------------- +**The MIT License (MIT)** +*Copyright (c) 2011 Erlware, LLC.* + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUqDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +Licenses for Software Parts of Jeringa Where Derived From +--------------------------------------------------------- + +### The Jeringa Arg Language + +The Jeringa Arg Language is derived heavily from [[docs/LYSP]]. The +original license on + +**Copyright (c) 2008 Ian Piumarta** +*All Rights Reserved* + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +'Software'), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, and/or sell copies of the Software, and to permit persons +to whom the Software is furnished to do so, provided that the above +copyright notice(s) and this permission notice appear in all copies of +the Software. Inclusion of the the above copyright notice(s) and this +permission notice in supporting documentation would be appreciated but +is not required. + +THE SOFTWARE IS PROVIDED 'AS IS'. USE ENTIRELY AT YOUR OWN RISK. + diff --git a/README.md b/README.md new file mode 100644 index 0000000..7d1fc56 --- /dev/null +++ b/README.md @@ -0,0 +1,50 @@ +Jeringa +======= + +What is Jeringa +--------------- + +Jeringa is a single file executable for Erlang/OTP releases. That is, +it allows you to create a normal Erlang release tarball, attach it too +Jeringa and have a single file that is runnable on the target +system. No preinstalled Erlang, no preinstalled libraries, everything +you need is right there in the executable and Jeringa makes it happen. + +This is very much in the same lines as +[PyInstaller](http://www.pyinstaller.org/) for Python or, +[RubyScript2Exe](http://www.erikveen.dds.nl/rubyscript2exe/) for Ruby, +This approach applied to Erlang Releases works very well. + +What Jeringa is Not +------------------- + +Jeringa is not a builder. That is Jeringa does not build the +executables for you, it enables the executables to be built. You must +assemble the executable yourself. You can do this manually very easily +or via a build system. Some build systems, like Sinan have built in +support for Jeringa. However, building the exe itself is pretty easy +with just a few unix command line tools. + +How to Build a Jeringa +---------------------- + +You may build a Jeringa executable simply by concatinating three files +together. The first file is the Jeringa executable itself. The second +file is a discriptor that helps Jeringa know how access the +archive. The third is the Erlang/OTP release tarball that you have +previously created (remeber Jeringa is not a builder). + +Assuming you are in the root of the Jeringa project run the following +command. + + :::sh $> cat jeringa misc/splt <path-to-my-release> > <my-executable> + +Remember to replace <path-to-my-release> with the path to your +correctly formatted Erlang/OTP release tarball and replace +<my-executable> with whatever executable name you desire. + +More Information +---------------- + +For more information check out the documentation. You can start out +with [[docs/HowItWorks]] and go from there. diff --git a/docs/Clang.md b/docs/Clang.md new file mode 100644 index 0000000..0842450 --- /dev/null +++ b/docs/Clang.md @@ -0,0 +1,5 @@ + +apt-get install clang +apt-get install binutils-gold + +- [Blocks Article](http://thirdcog.eu/pwcblocks/) diff --git a/docs/CodingStyle.md b/docs/CodingStyle.md new file mode 100644 index 0000000..fc4ec69 --- /dev/null +++ b/docs/CodingStyle.md @@ -0,0 +1,3 @@ + + + * http://eli.thegreenplace.net/2009/04/27/using-goto-for-error-handling-in-c/ diff --git a/docs/HowItWorks.md b/docs/HowItWorks.md new file mode 100644 index 0000000..5c6fff5 --- /dev/null +++ b/docs/HowItWorks.md @@ -0,0 +1,232 @@ +How It Works +============ + +First lets lay down some terminology so we are all talking about the +same thing. + +Jeringa +: This is the name of this project as well as the base name of the +executable built by the build system in this project. +Jeringa Derived Executable +: A Jeringa Derived Executable is an executable that is the +combination of three files. The Jeringa executable, the demarcation +file and an Erlang/OTP Release. +JEDE +: A shart name used as a synonym for Jeringa Derived Executable +Erlang/OTP Release +: This is a normal Erlang release. They are a fundamental building +block for Jeringa. If you are unfamiliar with them take a look at +[the documentation](http://www.erlang.org/doc/design_principles/release_handling.html) +or the book +[Erlang and OTP in Action](http://http://www.manning.com/logan)[^disclaimer] + +A JEDE is composed of three parts. The first part is the Jeringa +executable itself, this is followed by a sequence of bytes that +indicate a demarcation line between the executable and the Erlang/OTP +release tarball that follows. We need this because we need to be able +to tell where the executable ends and the tarball begins. + +The JEDE searches itself for the demarcation sequence of bytes. Then +extracts the tarball that follows to a working directory (where and +how that working directory is found comes later in this +document). Once everything is on the system, we can launch erlang in a +normal way on the release in the working directory. + +This process is seperated into four main parts. + +1. Figure out the Working Directory +2. Finding and extracting the Erlang/OTP release +3. Figuring out what arguments to pass to the Erlang Runtime System +4. Launching the Erlang Runtime System with the appropriate arguments + on the Release included in the tarball. + +Figuring out the Working Directory +----------------------------------- + +If the user does not specify anything the working directory location +defaults to the 'SystemTempDir'/'UserName'. However, this can be +overridden in multiple ways. In order of precedence. + +1. Pass a '-w=<dir>' or a '--working=<dir>' the Jeringa command + line. +2. Net the environmental variable 'JERINGA_WORKING_DIR' to the path you + would like to be your default extract target. +3. The default 'SystemTempDir'/'UserName'. + +Although the default setting tries to avoid it, it should be ok for +every one on the system to use the same directory, as long as the +versioning of the Release is consistant and good. Of course, in a +situation where the working directory is shared, there is nothing to +stop a malicious user from going through and manipulating the code run +by other users. So on non-single user systems you will almost +certainly want to set the JERINGA_WORKING_DIR env variable, or pass the +--working on the command line. + +Finding and Extracting the Release +---------------------------------- + +Once the working directory is found, jeringa uses the first argument +of the argv array as the name of the executable to search, when +looking for the tarball. This should work in almost every case. The +only case that might be problematic is when the Jeringa Derived +Executable is called by another program. In those cases, the program +must make sure that the first argument is the path it passes to to the +Jeringa Derived Executable is the path to the Jeringa Derived +Executable. + +The executable derived from Jeringa is a compound +executable. Consisting of three parts. The second part is the part +that is of interest to us here. That part is the demarcation bytes. At +the moment these demarcations consist of 42 consecutive instances of +the word 'SPLIT_' in ASCII encoding. + +Once thing to realize is that an Jeringa derived executable only +extracts a named release once. That is, once the Release is extracted +it wont do the extraction again. So if your extracted release gets +corrupted for any reason, you may need to delete the release in the +working dir. Then Jeringa will re-extract the release for you once +more. + + +Figuring Out what Arguments to Pass to the Runtime System +--------------------------------------------------------- + +Arguments can be a source of confusion. There are three interacting +environments in a JEDE. + +- The Jeringa Executable +- The Erlang Virtual Machine +- The Erlang/OTP Release + +Each of these need to be able to get these environments needs to be +able to get its own arguments, but in a way that is not intrusive to +the final user of the JEDE. To that end we have come up with a +convention for arguments. By default all arguments are passed to the +Erlang/OTP release with the '-extra' argument in the Erlang VM. You +can force arguments to be passed to the other levels by separating the +arguments with the -- arg. However, when passing this -- to force +arguments to the different environments you must pass arguments to +each environment you care about, from left to right. Lets work through +a couple of examples. Lets say I have turned sinan into a JEDE. If I +call sinan with a simple set of arguments it all gets passed directly +to the sinan release. + + :::sh + $ sinan shell + +In this case, (where sinan is a JEDE) it gets turned into a call to +the vm that looks something like. + + :::sh + $ erl -conf ... -boot ... -extra shell + +where the ellipses would be replaced with actual args of course. But +lets say we wanted to pass a working dir to the sinan JEDE as well as +the shell argument. What would we do? We need to make use of the +slightly more advanced argument parsing. + + :::sh + $ sinan --working ~/.jeringa/ -- -sname foo -- shell + +Whats going on here? Well the first set of arguments before the -- +gets passed to the Jeringa executable itself and consumed there. The +second set of arguments, in this case containing the node name for +erlang gets passed as additional arguments to the Erlang VM and the +third set of arguments gets passed to the Erlang/OTP Release as -extra +arguments. + +What happens if we want to pass arguments to one environment and not +the other. We still need to pass the space for the arguments. So lets +take our example above and posit that we do not need to pass the +erlang node name to the Erlang VM. + + :::sh + $ sinan --working ~/.jeringa/ -- -- shell + +Notice that the separators, '--', still exist, but where the VM +arguments used to be the area is empty. This tells the arguments +parser that there are no arguments for the vm in this command. + +What about the case where we want to pass vm arguments but not Jeringa +arguments? We can do that using the same model. + + :::sh + $ sinan -- -sname foo -- shell + +As you can see, we do the exact same thing. Leaving a space for right +after the JEDE name for those arguments that we do not want to +specify. Now what if we only want to specify Erlang/OTP args? Well +again, the same thing applies + + :::sh + $ sinan -- -- shell + +Of course, this is very much the common case. So we have given you the +shortcut we described above and show again below + + :::sh + $ sinan shell + +### Custom VM Args + +In reality you probably do not want your user passing args to anything +but the release. So what do you do when you need to specify custom VM +args based on the args that the user is passing to the Release, but do +not want to force your user to input those arguments? A great example +of this is the sinan shell command. For almost every command that you +can pass to sinan the Erlang VM arguments look the same, with the +exception of the shell command. The commands generally look like: + + :::sh + $ erlexec -config $CONFIGFILE -boot $BOOT_FILE -noshell -run sinan main + +However, for the sinan shell command the noshell needs to go +away. That is we want the normal Erlang shell to be available with all +its goodness. So for sinan shell the erts arguments look like the +following: + + :::sh + $ erlexec -config $CONFIGFILE -boot $BOOT_FILE -run sinan main + +Notice the missing '-noshell' argument. This is going to be a common +problem. Basically, we need to give the JEDE creator the ability to +manipulate the Erlang VM arguments. Great you say, the Release Creator +can just do it after his Release starts. Well there is actually a bit +of there. We need these arguments before the Erlang VM starts, we +can't wait until the Erlang VM starts to handle these arguments, so +what do we do? + +Well we need to embed a little DSL in Jeringa to give the Release +Creator the ability to manipulate args before the VM is started. So +what we have done is taken an extremely stripped down version of Lua +5.1 and embedded it in Jeringa to give you the ability to manipulate +args. Why not Erlang, well a couple of reasons. The biggest is that +Erlang is not really geared to being embedded in another application, +called yes, easily but embedded no. The second is that starting up the +Erlang VM is actually pretty slow comparatively and we expect JEDEs to +be heavily used in user facing applications, more so then servers. So +that dual VM start cost is prohibitive. + +So how do you use this. Just stick a jeringa/args file inside of your +release tarball. Jeringa will look for and run a function called +process_args where the argument to that function is the incoming +arguments and the return value a list containing all the new +arguments. + + + +Launching the Erlang Runtime System +----------------------------------- + +In general, its best if you include the Erlang Runtime System in your +Release. However, at times it may not be convenient to do +that. Jeringa is built with that eventuality in mind. So while the +default case is that it uses the erts in the Release, if no ERTS is in +the release, it will try to find a valid version of ERTS on the users +system and use that. The user may also over ride the ERTS that Jeringa +uses by providing an '-e=<erts-dir>' or '--erts_dir=<erts-dir>' to the +derived executable. In any case, once Jeringa has verified that it has +a good erts it will continue on to the next step. + + +[^disclaimer]: I am one of the authors of Erlang and OTP in Action -- 1.7.5.2 -- You received this message because you are subscribed to the Google Groups "erlware-dev" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/erlware-dev?hl=en.
