[TUT] Creating OEM's for your ROM

[rstoyguy]

This tutorial is designed to teach you the method I use to make simple OEM's.

Not all .cabs can be made into OEM's. Some will need some advanced trickery. This thread will be open to discussing that advanced trickery. I will answer any questions that arise, and other members can share their experiences/knowledge as well.

Not all topics are going to be added to this initial release, but I will add them with time, So check back later for more details!

Insert bold colored disclaimer here about how it is not my fault
if you mess up your phone or lose sleep after reading this tutorial...

Thanks go's out to:
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
- Ervius @ xda. It's his program
- PPCGeeks.com users. I've learned most everything here and can't list everyone.


Misc. Stuff
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
- For this Tutorial, Ervius's Package Creator will be reffered to as EPC.
- Here are some links to some other tutorials that may be helpfull when making OEM's:


Prerequisite Reading, Recommended...
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Tutorial: Adding Registry Entries to your Rom (RGU Method) - Helpfull for learning the RGU structure
Customizing Your Rom: Adding Personal Files & Other Stuff - Helpfull information on the initflashfiles.txt file.


What is an OEM?
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
An OEM... It's a package that Rom Chef's use to install files into a Rom. once a Rom is flashed, .cab files are installed. Cab files are converted to an OEM so those programs can be installed into a rom. Not a good definition, but it'll do.


Files inside an OEM, What are they?:
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
{guid}.DSM - I don't know the contents, I don't care, never needed them, so who cares what it contains? It's just gotta be there...
{guid}.RGU - This file contains the registry entries for your OEM
initflashfiles.txt - This file copies your files to where they need to be when winmo starts.
option.xml - This file is needed by BuildOS. Specifies the Name, GUID, BuildOS description, other OEM requirements, etc...

Everything else should be from your .cab file


Prepare your HDD
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
By this I mean, download the attachments. Here is a look at my directory structure looks like on my harddrive where I prepare my OEM's:
..\oem_requests
..\oem_requests\vga_oems
..\oem_requests\regular_oems
..\oem_requests\ervius package creator
..\oem_requests\a_c

When you are doing OEM's, EPC will create your oem's directory directly off of where your input cab was. So I would place my cab files in the appropriate directory.

So decide how you want to do it, make your directories, unarchive the attached EPC, and copy the attached Kevtris.cab to your new OEM directory. Once you've got that done, here is a walkthrough of making an OEM out of kevtris.cab


Let's build a simple OEM from Kevtris.cab:
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
1. Open Ervias's Package Creator 5.4

2. Click the "Open Cab File" button bottom left

3. Select your .cab file and click "Open"
(This will open your .cab with a program called "WinCE CABs Analyzer" program)

4. On the top row, Click the 7th icon from the left. When you roll your cursor over it, it will say "Extract CAB Files with original name in folder". This will open a directory selection window, DO NOT CHANGE THIS, I ALWAYS just click the "OK" button

5. Once this is done, you can exit WinCE CABs Analyzer simply by clicking the "Red X" in the top right corner.

6. This will take you back to EPC to the initflashfiles tab. This where you create your start menu shortcuts. For this example, click kevtris.exe in the window, select the Games button, and then click apply. You should see that it created/added Kevtris.lnk.
Click the "Done" button on the left, this will take you back to the main screen.

7. Here, click "Complete Package" and the program will tell you that you are Done, and you are.

Now back to your File Explorer, you will notice that a new directory was made where the original .cab file was, this is your OEM. Copy to your kitchens ..\kitchen\OEM folder and enjoy. If you are using PPCKitchen.orgs kitchen, copy the OEM into your ..\USeR_OEM folder and restart BuildOS.
I've included a basic .cab file and it's finished OEM. Here are a few notes on this one.
- This contains a SetupDLL.dll file... You know how when you install some cAB's they prompt you for your language, screen resolution, unzips files (weatherpanel), etc??? This file is responsible for this. Now while this one does nothing, I always delete them. You will have to figure out what it does and manually adjust your OEM to compensate. Each one will be different and will come to you with experience.

Figure 1: Screen shot of Main Screen w/correct options selected.


Figure 2: Screen shot of WinCE CAB Analyzer and location of the 7th Icon



Figure 3: Screen shot of the initflashfiles tab

[rstoyguy]

Advanced Topics & Tricks:
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
1: Tweaking the "option.xml"
2: Tweaking the "initflashfiles.txt"
3: Importing Program Settings
4: Handling the Setupdll.dll file
5: Adding multiple files using OEMIzer (Good for Skins-n-Things)


Advanced Topics: Tweaking the "option.xml"
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
The file option.xml is basically for BuildOS. Here is the contents from a freshly made OEM:

<?xml version="1.0" encoding="UTF-16" standalone="yes"?>
<Items>
  <Item name="Kevtris" group="Apps" checked="True">
    <Tip></Tip>
    <Guid type="p">e29023a8-1df6-47e1-8b01-4c94430ece83</Guid>
  </Item>
</Items>

Now let's take a look at each one:
Kevtris - This is the name that show up in BuildOS
Apps - This is the category sub-folder that the program will show up in BuildOS.
True - True, it is checked when BuildOS is first started and will be included in the build. The other option is "False" for it will not be checked.
Tip - This is the program description when you roll your mouse over that option in BuildOS (older) or to the right of the program name in the newer kitchen.
Guid Type - This is the GUID of the OEM, the DSM and RGU files have this same name as well.

Now let's add a few more components to the file.

<?xml version="1.0" encoding="UTF-16" standalone="yes"?>
<Items>
  <Item name="Kevtris" group="Apps" checked="True">
    <Tip>Kevtris for winmo</Tip>
    <OEMAuthor>rstoyguy</OEMAuthor>
    <OEMDate>1/1/2009</OEMDate>
    <OEMVersion>1.00</OEMVersion>
    <AppVersion>0.xx</AppVersion>
    <AppAuthorURL>www.google.com</AppAuthorURL>
    <Guid type="p">e29023a8-1df6-47e1-8b01-4c94430ece83</Guid>
  </Item>
</Items>

Above I've added, the OEM Date, Author, Version, and a URL link. The information in orange is just text format. Adding this information is handy, especially if your using the latest ppckitchens buildos.


This is a text file I keep so I can easily cut and paste the above information into the option.xml of most of the OEM's I do.

    <OEMAuthor>rstoyguy</OEMAuthor>
    <OEMDate>12/9/2008</OEMDate>
    <OEMVersion>1.00</OEMVersion>
    <AppVersion>0</AppVersion>
    <AppAuthorURL></AppAuthorURL>

Other option.xml commands are:
<Require> {GUID} </Require> - Adding this line will require BuildOS to include that OEM as well. Replace the {GUID} with the actual GUID of the OEM.

Originally Posted by GGuruUSA

Beyond the basic tags, here's a list of PPCkitchen specific tags you can use in an option.xml file to make your kitchen more friendly. These tags are all optional.

Simple ones everyone should include:
<OEMDate> - Date the package was last modified
<OEMVersion> - package version (not necessarily the same as app version)
<OEMAuthor> - person to contact regarding the package
<AppVersion> - verison of the application
<AppAuthorURL> - author of the application
<LicenseType> - applications license model (freeware, shareware, commercial, subscription, etc)
<AdditionalInfo> - any additional info to describe the package/application

BuildOS display tags:
<CarrierModule> - package will appear and be selected from Carrier dropdown
Build controlling tags:
<Exclude> - Exclude the package with matching GUID (prebuild) when this package included
<Require> - Require the package with matching GUID (prebuild) when this package included
<RequireDeviceFeature> - this package Excluded if feature doesn't exist (prebuild)
<NeededForFeature> - this package Required if feature exists (prebuild)
<Features> - features this package adds (e.g., .NetCF35 package could have .NET and .Net35 features, which other packages might use in <RequireDeviceFeature> tags)
<SkipFile> - causes the named package file to NOT be include in the build
<PatchOEM> - this package is used to patch another package. This package is excluded if package to be patched is not included. Inclusion of package to be patched does NOT auto include this package.

Advanced Topics: Tweaking the "initflashfiles.txt"
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Here is a look at the file:

;*****************************************************************************
;initflashes.txt created with packages generator by ervius!!!
;package: Kevtris
 
Directory("\Program Files\"):-Directory("Kevtris 2")
Directory("\Program Files\Kevtris 2"):-File("176x220.dll","\windows\000-176x220.dll")
Directory("\Program Files\Kevtris 2"):-File("240x240.dll","\windows\000-240x240.dll")
Directory("\Program Files\Kevtris 2"):-File("240x320.dll","\windows\000-240x320.dll")
Directory("\Program Files\Kevtris 2"):-File("Kevtris.exe","\windows\000-Kevtris.exe")
Directory("\Program Files\Kevtris 2"):-File("SetupDLL.dll","\windows\000-SetupDLL.dll")
Directory("\Program Files\Kevtris 2"):-File("sounds.dll","\windows\000-sounds.dll")
 
Directory("\windows\start menu\programs\games"):-File("Kevtris.lnk","\windows\Kevtris.lnk")
 
;Help files:
;end of package: Kevtris
;*****************************************************************************

Sometimes cabs will install some additional .lnk files, misplace a file that got copied into the program directory that should have been left in the \windows directory, or will have multiple language files and depending on your language selection will copy only one to a different filename inside the program directory. I almost always anymore copy my .links from the device after a .cab install. I check the \windows\startup and \windows\program files directories. I then manually copy them from my device into the OEM and create an initflashfiles.txt entry for it. Other files, you will have to install the .cab on your device, then examine the structure within the OEM and adjust your OEM so it mimics the .cab install file placements, etc...

I've already covered handling this file in some other tutorials. So check out this tutorial to find out more:

Customizing Your Rom: Adding Personal Files & Other Stuff (the beef is in post #2 for those quick learners)

[rstoyguy]

Advanced Topics: Importing Program Settings
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Reserved for later...

Advanced Topics: Setupdll.dll
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
This file sometimes has some additional code that will run doing a .cab install. When installing a .cab on Windows Mobile, there are four "Hooks" that winmo looks for when dealing with .cabs. There are only two that we are concerned with. There is a "hook" that is called before the .cab is installed and another one after the .cab is installed. If this file is present, more than likely there is something more and YOU WILL HAVE TO MANUALLY EDIT YOUR OEM.

Etiquette Note: This file is almost always and exclusively used in this fashion, and some PPCGeeks etiquette...If an OEM contains this file, it is considered a "poorly" put together OEM. This file will also almost always create that "Duplicate File" error is BuildOS (or whatever else you use) so just get rid of it!

Here are some things it can do:
MemMaid: Calls that little help screen (harmless), PocketTunes: Displays a license agreement (harmless), WeatherPanel: UnZips all the graphics files, Touchpal: Prompts you for your device type and then copies the VGA/QVGA files depending on your choice... Those are just a couple, thank goodness that this is not used much, but it is out there.

How to defeat it:
You will need to install the .cab to your device, preferably to a clean rom. Then you will have to match up the files from the OEM to where the files were installed on your device. Then edit the initflashfiles.txt, and files in your OEM to make the changes. I'm not going any further with this, YOU will have to figure it out. There are just too many variables and it just takes experience... You can always visit one of my oem requests threads and request it. If you ask I will actually post the "trickery" I found briefly.


Advanced Topics: Adding multiple files using OEMIzer (Good for Skins-n-Things)
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
I don't use the OEMIzer much, but I have found it a very good use for it. Say you are wanting to install a skin that installs all the files to \program files\weatherpanel\skins and all you have is a zip file with those files. Here is a brief how-to do that...

Create in your oem-making directory a directory called ..\oemizer, the inside create two directories, ..\oemizer\oemizer and ..\oemizer\OEM. Copy the 3 oemizer files from one of blank kitchens (found in my Adding/Removing Programs Tutorial in my sig) into the ..\oemizer\oemizer directory.

Now that your prepped, let's do it!
Open up OEMIzer and move the window to the left side of the screen, then open up a windows explorer window and move it the right side so you have the two windows open in a side-by-side style.
In OEMIzer, click the "Files and Shortcuts" tab and make sure its checked.
Next, from your file explorer, select and drag-n-drop those files into the OEMizer window.
Now in OEMizer, select all the files in the window.
Down below in the box that says "\windows\", change this filename to where you want your files installed. Be sure to put a trailing \, so it's "\program files\weatherpanel\skins\".
Now click the "edit" button. You should see that this changed all the items in the window.
Now your ready to make the OEM, so click the Green globe above that says "Create OEM".

Your oem was created in the ..\oemizer\oem directory. Now what I do is copy the files into the OEM I was creating, and APPEND the contents of the initflashfiles.txt from the newly created OEM into the one I was originally working with.

It can be a pain to manually create an initflashfiles entry when your skin is 400+ files, I've found this to be a huge timesaver!

[rstoyguy]

Originally Posted by aceracer24

Thanks rstoyguy. I kind of figured that but thought it was worth asking.

Another question I have has to do with Sprints Picture mail. I have converted the newest one to an OEM. The problem I am having with it is that on the email tab of TF3D there is no icon for Picture mail. There is no Picture mail under accounts either. The only way I can send a picture mail is by actually going into the folder that has pictures and selecting picture mail from there.

I have gone through the entire reg on my phone after installing picture mail with the cab and included everything I could find but I must be missing something. Right now the only way to get an icon for Picture mail on the email tab is to actually install it with the cab. Any help would be appeciated.

I haven't looked at that .cab in a while, but doesn't it just install extensions so you can use picturemail? I still use sMMS. You will have to setup an account for that using the EMAIL2 provisioning for it to show up I beleive.

[aceracer24]

Sorry about posting in your other thread

Honestly, I don't know. I am still pretty new at OEM creating and rom building in general.

Did i miss something about email provisioning? Where can I learn about that? It might be just that simple...isn't that something that can be done in OEMizer? It makes sense now that you mention it since it does add to the email tab it probably works just like email. I don't set up my email through the tab. I use Seven and set up email that way...I still need to work that out as well so I don't have to manually setup Seven.

[rstoyguy]

I don't mind answering questions to the best of my ability, just don't want my other thread....well...

Learn about EMAIL2 configurations service in the following thread, post #5
http://forum.ppcgeeks.com/showpost.p...76&postcount=5

[aceracer24]

Ok, I read over this EMAIL2 thing. Been trying to wrap my head around it all day actually. I assumed that some of those setings would already bee in teh registry in order for picture mail to be identified but I have not seen anything associated with Picture mail and anything in the EMAIL2 provisioning. Even if I did set up according to that, I am not sure where I would get even half of the settings that need to be used in it.

[rstoyguy]

Originally Posted by aceracer24

Ok, I read over this EMAIL2 thing. Been trying to wrap my head around it all day actually. I assumed that some of those setings would already bee in teh registry in order for picture mail to be identified but I have not seen anything associated with Picture mail and anything in the EMAIL2 provisioning. Even if I did set up according to that, I am not sure where I would get even half of the settings that need to be used in it.

I use it to setup my gmail accounts. But for picturemail, I registered sMMS that's made from some mms guy, don't really know who...lol back on track. But I registered sMMS, and exported the settings into an OEM that takes care of my personal settings/registrations. But I send like one pic per month...

edit: I have heard that some have just copied \cemail.vol over and cook it into their roms...

[gguruusa]

{guid}.DSM - I don't know the contents, I don't care, never needed them, so who cares what it contains? It's just gotta be there...

It's a manifest file. In a nutshell, it's the module name and version, target processor, and file list. Some .dsms have more stuff in them.

They are mostly rebuilt when you build, which is why you can mostly ignore them. I think they're completely ignorred in Bepe's latest kitchen.

[gguruusa]

Other option.xml commands are:
<Require> {GUID} </Require> - Adding this line will require BuildOS to include that OEM as well. Replace the {GUID} with the actual GUID of the OEM.

Oh, there are more now.

See this: PPCkitchen BuildOS tags