documentation/getting_started.pod
author Tom Sutcliffe <thomas.sutcliffe@accenture.com>
Fri, 13 Aug 2010 16:18:06 +0100
changeset 32 50af04b02d7d
parent 9 257450419d10
child 34 284c68d7a3ac
permissions -rw-r--r--
Updated getting started guide with mercurial locations
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
0
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
     1
#!perl
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
     2
# getting_started.pod
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
     3
#
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
     4
# Copyright (c) 2008-2010 Accenture. All rights reserved.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
     5
# This component and the accompanying materials are made available
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
     6
# under the terms of the "Eclipse Public License v1.0"
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
     7
# which accompanies this distribution, and is available
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
     8
# at the URL "http://www.eclipse.org/legal/epl-v10.html".
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
     9
#
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    10
# Initial Contributors:
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    11
# Accenture - Initial contribution
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    12
#
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    13
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    14
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    15
__END__
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    16
8
eb5f524dc31d Fixed TEF depenancies for SF builds. Enabled SPCRE and grep by default.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 0
diff changeset
    17
=head1 Getting started with FShell
eb5f524dc31d Fixed TEF depenancies for SF builds. Enabled SPCRE and grep by default.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 0
diff changeset
    18
0
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    19
=head1 Retreiving the FShell Source Code
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    20
32
50af04b02d7d Updated getting started guide with mercurial locations
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 9
diff changeset
    21
fshell is hosted on the Symbian Foundation here: http://developer.symbian.org/main/source/packages/fshell
50af04b02d7d Updated getting started guide with mercurial locations
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 9
diff changeset
    22
50af04b02d7d Updated getting started guide with mercurial locations
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 9
diff changeset
    23
To clone the MCL repository, do:
50af04b02d7d Updated getting started guide with mercurial locations
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 9
diff changeset
    24
50af04b02d7d Updated getting started guide with mercurial locations
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 9
diff changeset
    25
    hg clone https://developer.symbian.org/oss/MCL/sf/os/fshell/
0
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    26
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    27
=head1 Building FShell
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    28
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    29
FShell is normally distributed in source code form, and so needs to be compiled before it can be used. The conventional Symbian build tools -- either SBSv1 (aka abld) or SBSv2 (aka Raptor) -- are used. Currently three Symbian OS based platforms are supported:
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    30
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    31
=over 5
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    32
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    33
=item * Symbian Foundation (S^2 and S^3)
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    34
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    35
=item * Nokia S60 (3.x and 5.x)
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    36
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    37
=item * Nokia Symbian Timebox 9.2
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    38
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    39
=back
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    40
32
50af04b02d7d Updated getting started guide with mercurial locations
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 9
diff changeset
    41
Each of these platforms have a separate directory within F<\fshell\build>. For some platforms there may be further separate sub-directories for specific variants of the platform. You need to identify a suitable directory (that contains a file named F<bld.inf>) from which to build from. For example to build for the Symbian^3 release you need to build from F<\fshell\build\sf\3>. Open a command prompt and C<cd> to this directory.
0
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    42
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    43
You also need to identify the type of binaries you want to build. Common ones are:
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    44
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    45
=over 5
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    46
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    47
=item * C<winscw>
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    48
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    49
Used for running fshell on the WINSCW emulator. Requires an installation of the CodeWarrior Win32 compiler.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    50
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    51
=item * C<armv5>
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    52
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    53
Used for running fshell on either physical or simulated ARM hardware. Requires an installation of ARM's RVCT compiler. Version 2.2 is commonly used on current Symbian based handsets.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    54
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    55
=item * C<gcce>
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    56
9
257450419d10 Fixes for GCC-E 4.4.1 and updated docs.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 8
diff changeset
    57
Used for running fshell on either physical or simulated ARM hardware. Requires an installation of the GCC crosscompiler (for arm-none-symbianelf) - see here for more information: http://developer.symbian.org/wiki/index.php/The_GCCE_toolchain_initiative.
0
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    58
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    59
=back
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    60
8
eb5f524dc31d Fixed TEF depenancies for SF builds. Enabled SPCRE and grep by default.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 0
diff changeset
    61
Lastly, you need to identify the build variant you plan to use, either debug (C<udeb>) or release (C<urel>). Commonly, C<udeb> is used on the emulator whereas C<urel> is used on target hardware. For the purposes of this introduction we will assume that you will be building C<winscw udeb> and C<armv5 urel>.
0
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    62
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    63
=head2 SBSv1 (aka abld)
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    64
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    65
  M:\fshell\build\s60\3>bldmake bldfiles
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    66
  M:\fshell\build\s60\3>abld build winscw udeb
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    67
  M:\fshell\build\s60\3>abld build armv5 urel
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    68
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    69
=head2 SBSv2 (aka Raptor)
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    70
8
eb5f524dc31d Fixed TEF depenancies for SF builds. Enabled SPCRE and grep by default.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 0
diff changeset
    71
  M:\fshell\build\sf\2>sbs -c armv5_urel
eb5f524dc31d Fixed TEF depenancies for SF builds. Enabled SPCRE and grep by default.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 0
diff changeset
    72
  M:\fshell\build\sf\2>sbs -c winscw_udeb
eb5f524dc31d Fixed TEF depenancies for SF builds. Enabled SPCRE and grep by default.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 0
diff changeset
    73
9
257450419d10 Fixes for GCC-E 4.4.1 and updated docs.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 8
diff changeset
    74
I<Note:> There are currently some concurrency issues in the build process that mean we don't recommend building multiple platforms in a single invocation of sbs. Ie do the above rather than C<sbs -c armv5_urel -c winscw_udeb>. In some cases you may even need to add the option C<-j 1> to sbs to have it run completely single-threaded. We'll fix this as soon as we can!
257450419d10 Fixes for GCC-E 4.4.1 and updated docs.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 8
diff changeset
    75
257450419d10 Fixes for GCC-E 4.4.1 and updated docs.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 8
diff changeset
    76
=head2 Notes on building for GCC
257450419d10 Fixes for GCC-E 4.4.1 and updated docs.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 8
diff changeset
    77
257450419d10 Fixes for GCC-E 4.4.1 and updated docs.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 8
diff changeset
    78
Fshell has only been tested to build with GCC-E 4.4.1, and the legacy 3.4.2.
257450419d10 Fixes for GCC-E 4.4.1 and updated docs.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 8
diff changeset
    79
257450419d10 Fixes for GCC-E 4.4.1 and updated docs.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 8
diff changeset
    80
I<Note:> The SF website appears to be out of date with regards to how to build with GCC-E on Raptor - at the time of writing the way to build is as follows:
257450419d10 Fixes for GCC-E 4.4.1 and updated docs.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 8
diff changeset
    81
257450419d10 Fixes for GCC-E 4.4.1 and updated docs.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 8
diff changeset
    82
  S:\fshell\build\sf\3>set SBS_GCCE432BIN=Nothing
257450419d10 Fixes for GCC-E 4.4.1 and updated docs.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 8
diff changeset
    83
  S:\fshell\build\sf\3>set SBS_GCCE433BIN=Nothing
257450419d10 Fixes for GCC-E 4.4.1 and updated docs.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 8
diff changeset
    84
  S:\fshell\build\sf\3>set SBS_GCCE441BIN=c:/apps/gcce/bin
257450419d10 Fixes for GCC-E 4.4.1 and updated docs.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 8
diff changeset
    85
  S:\fshell\build\sf\3>sbs -c arm.v5.urel.gcce4_4_1
257450419d10 Fixes for GCC-E 4.4.1 and updated docs.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 8
diff changeset
    86
257450419d10 Fixes for GCC-E 4.4.1 and updated docs.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 8
diff changeset
    87
You may also need to update the compiler support libraries - I had to unzip rt_3_1_bin.zip from \sf\os\kernelhwsrv\kernel\eka\compsupp from a different baseline. (Unzip over \epoc32\release\armv5). The working libraries I used had datestamp of 28/1/2009, the non-working ones were 1/1/2009.
257450419d10 Fixes for GCC-E 4.4.1 and updated docs.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 8
diff changeset
    88
257450419d10 Fixes for GCC-E 4.4.1 and updated docs.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents: 8
diff changeset
    89
There's one final gotcha if you want to build with GCC-E - at the time of writing the makefiles produced by SBS for PIPS executables is incorrect, therefore you need to add C<#define FSHELL_NO_PIPS_SUPPORT> to \fshell\build\sf\platform_shared.mmh. Hopefully this is a temporary measure.
0
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    90
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    91
=head1 Installation
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    92
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    93
Having performed a build, you should have a full set of binaries in your F<\epoc32> tree. If you want to run fshell on the emulator, no further action is necessary. If you want to run fshell on the simulator or target hardware, then the fshell binaries need to be either added to a ROM image or installed at runtime.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    94
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    95
=head2 Adding FShell to a ROM Image
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    96
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    97
This is probably the easiest approach, assuming you have a means of reprogramming the ROM of the hardware you plan to use. By putting fshell in the ROM, the complexities of platform security are normally avoided.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    98
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
    99
Detailed instructions for building a ROM image for your hardware are outside of the scope of this document, however adding fshell fundamentally boils down to adding F<\epoc32\rom\include\fshell.iby> to your ROMBUILD scripts. Often the easiest way to do this is to add the following line to your main F<.oby> file:
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   100
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   101
  #include <fshell.iby>
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   102
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   103
Alternatively, depending on how you're building the ROM you can specify additional F<.oby> or F<.iby> files as command line arguments. For example:
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   104
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   105
=over 5
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   106
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   107
=item * buildrom
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   108
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   109
  buildrom techview fshell.iby
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   110
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   111
=item * imaker
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   112
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   113
  imaker default BLDROBY="\epoc32\rom\include\fshell.iby"
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   114
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   115
=back
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   116
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   117
=head2 Installing fshell at Runtime
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   118
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   119
Another product of the fshell build is F<\epoc32\fshell\fshell.unsigned.sis>. This is a Symbian OS install file that contains precisely the same set of files that F<fshell.iby> refers to. There are however some additional hurdles that need to be negotiated in order to be able to install the SIS file.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   120
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   121
=over 5
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   122
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   123
=item 1
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   124
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   125
Most production handset will not allow unsigned SIS files to be installed. The SIS file that the fshell build process produced must therefore be signed first. The Symbian Foundation provide a tool called F<signsis.exe> to perform the signing, however you need to get hold of a suitable certificate to sign with. Refer to http://www.symbiansigned.com/ for more details. Building on some platforms may automatically generate a signed SIS file F<\epoc32\fshell\fshell.sis> if there is a standard certificate for the platform.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   126
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   127
=item 2
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   128
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   129
By default the fshell build produces binaries that use B<all> security capabilities (including C<TCB>). When they are installed at ROM build time, this isn't a problem. However, SIS files are generally restricted in the set of security capabilities that they can be signed for. To cater for this, you will need to restrict the fshell build to the set of capabilities that you are able to sign for. This is done by editing your platform's F<platform.mmh> (or in the case of platforms that support multiple variants, F<platform_(generic|shared).mmh>). You'll need to replace the following line:
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   130
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   131
  #define FSHELL_CAP_ALL
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   132
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   133
The file F<\fshell\build\common\common.mmh> contains definitions of the complete set of platform security macros that the fshell build system supports. For example, suppose you have access to all the user capabilities, your would replace the above line with:
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   134
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   135
  #define FSHELL_CAP_MMP_MAX localservices location networkservices readuserdata userenvironment writeuserdata
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   136
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   137
  #define FSHELL_CAP_LOCALSERVICES
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   138
  #define FSHELL_CAP_LOCATION
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   139
  #define FSHELL_CAP_NETWORKSERVICES
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   140
  #define FSHELL_CAP_READUSERDATA
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   141
  #define FSHELL_CAP_USERENVIRONMENT
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   142
  #define FSHELL_CAP_WRITEUSERDATA
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   143
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   144
The macro C<FSHELL_CAP_MMP_MAX> should be set to all the capabilities that you have access to. There is another macro C<FSHELL_CAP_MMP_NORMAL> which is what most DLLs and EXEs in fshell actually use. The difference is only important if you can sign for all capabilities (ie C<FSHELL_CAP_MMP_MAX> is C<All>) - in this case C<FSHELL_CAP_MMP_NORMAL> is set to C<All -TCB> to make sure you can link against normal DLLs.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   145
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   146
The act of defining the above macros may cause certain fshell binaries not to be built (for example, if the bianry can't do anything useful unless a particular capability is available). However, F<fshell.iby> and F<fshell.unsigned.sis> should automatically accommodate for the missing binaries without any further action on your part. If they don't, please contact the maintainers of fshell because that's probably a bug!
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   147
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   148
=item 2
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   149
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   150
Depending on the configuration of the target handset's certificate store and the key you are signing with, you may also need to use UIDs from the non-protected range. By default the fshell builds with UIDs from the protected range. To change this, remove the definition of C<FSHELL_PROTECTED_UIDS> from your platform's F<platform.mmh>. Note however, that currently the fshell's non-protected UIDs are not properly allocated UIDs. Rather they are the protected UID values but with the top nibble changed from 0x1 to 0xE. It is therefore possible (albeit pretty unlikely) that they could clash with UIDs used in other software.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   151
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   152
=back
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   153
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   154
If you needed to change your F<platform.mmh> to satisfy platform security requirements, you'll need to perform a re-build of the source. It's advisable to run C<abld reallyclean> (or C<sbs reallyclean>) before doing this to ensure that everything is fully re-built.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   155
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   156
Having built and signed a SIS file, it can be installed by copying it to a memory card and inserting this in the target hardware. Details of how to do this for your particular hardware are outside of the scope of this document, but normally there's a File Manager type application that can be used to launch the SIS file. Alternatively, some handsets provide a PC Connectivity Suite that can be used to install SIS files from your PC.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   157
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   158
=head2 Running FShell
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   159
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   160
Once fshell has been installed, the following icons should appear in the menu application*:
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   161
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   162
* Note, the folder in which the icons can be found varies between hardware and software platforms. For S60, try looking in "Installations", "Installed", "Applications" or "Applications->My Own".
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   163
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   164
=over 5
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   165
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   166
=item * fshell
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   167
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   168
This icon will launch an L<fshell|fshell> instance using the default console. Where supported, this will be fshell's own GuiCons console, but on platforms where this isn't supported it will fall back to the Symbian Foundation F<econs> or F<econseik> consoles (see L<consoles|plugins::consoles> for a discussion of the various consoles that fshell supports). This puts up a full-screen window and allows text input via whatever keyboard the handset has. It is certainly the easiest console to get going with, but (depending on the handset you're using) entering text can be fairly tiresome.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   169
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   170
=item * fshell (USB)
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   171
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   172
This icon will launch an L<fshell|fshell> instance that is connected to a remote terminal (e.g. HyperTerminal) via USB. The following steps must be taken before using this launch method:
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   173
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   174
=over 5
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   175
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   176
=item 1
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   177
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   178
Install the PC Suite USB drivers applicable for your device.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   179
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   180
=item 2
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   181
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   182
Connect your handset to your PC via USB.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   183
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   184
=item 3
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   185
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   186
On your handset, if a dialog appears asking what USB service to use, select "PC Suite". You may have to change the USB settings in the control panel if you don't see this dialog.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   187
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   188
=item 4
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   189
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   190
On your PC determine the name of the virtual serial port associated with your device. This can be done by right clicking on "My Computer", selecting "Manage". Then select "Device Manager" and expand the category "Ports (COM & LPT)". You should see one of the ports labelled something like "Nokia N96 USB". Make a note of the name that follow this in brackets (e.g. "(COM7)").
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   191
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   192
=item 5
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   193
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   194
On your PC, open a terminal emulator (such as TeraTerm or HyperTerminal). Instruct this application to open the serial port you identified in the previous step. Set the bits per second to 115200, data bits to "8", parity to "None", stop bits to "1" and flow control to "None". HyperTerminal has many restrictions, so we generally recommend TeraTerm Pro 4.6, available from http://ttssh2.sourceforge.jp/ .
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   195
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   196
=item 6
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   197
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   198
Connect your terminal emulator to the port identified in step 4.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   199
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   200
=item 7
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   201
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   202
On your handset, tap "fshell (USB)". You should see a command prompt appear in your terminal emulator. If you don't you may need to reboot both your PC and your handset.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   203
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   204
=back
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   205
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   206
After you have finished using the command prompt, the 'polite' way to disconnect your handset is as follows. Generally if you're using recent software you can get away with just closing the terminal emulator and/or unplugging the cable (in either order). Less tolerant USB drivers may require you to take care to follow the instructions below:
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   207
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   208
=over 5
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   209
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   210
=item 1
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   211
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   212
Type "exit" to exit from fshell.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   213
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   214
=item 2
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   215
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   216
Disconnect your terminal emulator from the serial port.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   217
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   218
=item 3
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   219
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   220
Remove your USB cable.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   221
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   222
=back
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   223
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   224
To reconnect, repeat steps 6 and 7 above. (Reconnecting the USB cable and choosing the usb service, if necessary.)
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   225
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   226
=item * fshell (BT)
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   227
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   228
This icon will launch an L<fshell|fshell> instance using the Bluetooth variant of L<vt100cons|vt100cons>. Assuming your PC is paired with the handset, after launching this icon it should be possible to establish a serial connection from your PC to the handset. Once that has been done, HyperTerminal (or some other VT100 compatible terminal emulator) can be pointed at the PC side virtual serial port, and an fshell prompt should appear.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   229
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   230
=item * fshell (TCP)
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   231
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   232
This icon will launch an L<fshell|fshell> instance using the TCP variant of L<vt100cons|vt100cons> in passive mode. This means that the handset will listen for an incoming TCP connection on a particular port. After you launch the icon, you will first have to select the bearer for the TCP/IP session. Assuming it is available on your handset, WLAN is probably the best choice of bearer. Once the WLAN connection has been established, a console window should appear stating the IP address and port that is being listened on. Your PC will need to be connected to the same network. Open HyperTerminal (assuming you're using Windows) and connect using "TCP/IP (Winsock)" mode, specifying the IP and port displayed on the handset. An fshell prompt should appear in HyperTerminal.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   233
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   234
If you're using hardware that doesn't support WLAN, then all is still not lost. It is possible to establish a remote console session using a packet context. However, the hoops you have to jump through to achieve this are rather tighter than any of the other methods described. There are two main problems that have to be overcome. Firstly, most PCs don't have a public IP address, and so cannot be connected to directly. Secondly, most packet context connection don't have a public IP address, and so the same applies. The latter issue can be handled by using F<vt100tcpcons> in active mode (i.e. where it actively connects to a particular host). The first issue can be handled using an SSH tunnel. However, its not possible to configure an SSH tunnel that listens on both ends - one end must listen (i.e. be passive) and the other connect (i.e. be active). Because we need the end that F<vt100tcpcons> will be connecting to to listen, we need to provide something for the other end to connect to. This can't be HyperTerminal, because that only supports active connection. So instead we use C<com2tcp> (see http://com0com.sourceforge.net/) to listen on a particular port and then present this as a virtual serial port that HyperTerminal can connect to. In a more visual form, we end up with:
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   235
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   236
  |   Handset        |       SSH Server     |                               PC                                 |
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   237
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   238
  vt100tcpcons.dll  <-->  SSH tunnel end  <-->  SSH tunnel end  <-->  com2tcp  <--> com0com  <-->  HyperTerminal
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   239
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   240
All this can be achieved with the following steps:
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   241
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   242
=over 5
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   243
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   244
=item *
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   245
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   246
Install C<com0com>, C<com2tcp> and an SSH client (the example below uses OpenSSH provided by Cygwin).
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   247
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   248
=item *
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   249
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   250
Establish an SSH tunnel between your PC and an SSH server that has a public IP address:
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   251
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   252
  ssh <username>@<ssh_server> -R <ssh_server_IP>:8080:localhost:8080
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   253
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   254
Note, C<ssh_server_IP> is the public IP address of the SSH server. This is necessary ensure that the tunnel listens on the public IP rather than the loopback interface. If you're using OpenSSH, make sure that C<AllowTcpForwarding> is set to C<yes> on the server.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   255
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   256
=item *
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   257
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   258
Configure C<com2tcp> to listen on port 8080 of the PC's loopback interface:
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   259
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   260
  com2tcp \\.\<com0com_port_name> 8080
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   261
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   262
Note, C<com0com_port_name> is the name of one port of a virtual serial port pair provided by C<com0com>. You can create a suitable virtual serial port pair using "Start | Programs | com0com | Setup". Be sure to work your way through "New hardware detected dialogs" as the pop up (rather than simply dismissing them), because if you don't the ports won't be visible to Windows software. No actual driver file should be necessary.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   263
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   264
=item *
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   265
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   266
Open HyperTerminal and point it at the other port of the virtual serial port pair provided by C<com0com>.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   267
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   268
=item *
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   269
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   270
Configure F<vt100tcpcons> to use an outgoing TCP connection by running the following at an fshell prompt (you may need a "local" fshell prompt for this):
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   271
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   272
  fshell --console vt100tcpcons --console-title host=<ssh_server>,port=8080
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   273
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   274
=back
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   275
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   276
If all has gone well, you should see an fshell prompt in HyperTerminal.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   277
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   278
=back
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   279
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   280
=head1 Copyright
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   281
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   282
Copyright (c) 2008-2010 Accenture. All rights reserved.
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   283
7f656887cf89 First submission to Symbian Foundation staging server.
Tom Sutcliffe <thomas.sutcliffe@accenture.com>
parents:
diff changeset
   284
=cut